Superb AI API Keys API

openapi: 3.2.0
info:
  title: MLOps Platform API Keys API
  description: Multi-tenant labeling-platform backend.
  version: 0.1.0
tags:
- name: API Keys
paths:
  /tenants/{slug}/users/me/api-keys:
    post:
      tags:
      - API Keys
      summary: Create a new API key for the calling user
      description: 'Mints a new long-lived credential bound to the calling user. The plaintext is returned **once** in this response — store it securely (env var, secret manager). The server only retains an argon2id hash, so a lost plaintext cannot be recovered; revoke and re-create.


        Use the returned `plaintext` as a `Authorization: Bearer ` header to authenticate subsequent requests. The key inherits the user''s role; v1 has no scoping.


        **Capped at 1 active key per user.** To rotate, `DELETE` your existing key first, then `POST` to mint a fresh one. Without scopes there''s no functional reason to hold more than one.'
      operationId: api-keys-create_api_key
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - API Keys
      summary: List the calling user's active API keys
      description: Returns metadata only — never the plaintext. Use `prefix` to identify which key is which (the prefix is also visible in the API key itself, e.g. `sbd_pk_a3f4…`).
      operationId: api-keys-list_api_keys
      security:
      - HTTPBearer: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tenants/{slug}/users/me/api-keys/{key_id}:
    delete:
      tags:
      - API Keys
      summary: Revoke (soft-delete) an API key
      description: Sets `revoked_at`; the key is rejected on the next auth check. Idempotent — revoking an already-revoked key returns 404 (the list endpoint hides revoked keys, so a duplicate revoke would be operating on stale information; better to surface than swallow).
      operationId: api-keys-revoke_api_key
      security:
      - HTTPBearer: []
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Key Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthenticated — missing, malformed, or expired Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Authenticated but not authorized for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found in this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource state prevents this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limited (per-tenant token bucket)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ApiKeyCreate:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          title: Name
          description: User-supplied label so you can recognize the key later (e.g. "ci-cd", "my-laptop").
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: ISO 8601 timestamp after which the key stops authenticating; null or omitted means the key never expires.
      type: object
      required:
      - name
      title: ApiKeyCreate
      description: Body for `POST /api-keys`.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable; free to evolve. Don't pattern-match on this.
            hint:
              type: string
              nullable: true
              description: When present, a concrete next step (often references a CLI command).
            details:
              type: object
              nullable: true
              description: Per-`code` structured payload; schema documented per code.
            request_id:
              type: string
              nullable: true
              description: Correlation id for support / log lookups.
    ApiKeySummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Server-assigned unique id of the API key.
        name:
          type: string
          title: Name
          description: The user-supplied label for the key.
        prefix:
          type: string
          title: Prefix
          description: Short non-secret prefix of the key (e.g. `sbd_pk_a3f4…`), used to identify which key is which.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the key was created.
        last_used_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used At
          description: When the key was last used to authenticate; null if never used.
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: When the key expires; null means it never expires.
      type: object
      required:
      - id
      - name
      - prefix
      - created_at
      - last_used_at
      - expires_at
      title: ApiKeySummary
      description: List response item. Never carries the plaintext.
    ApiKeyList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ApiKeySummary'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: ApiKeyList
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ApiKeyCreated:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Server-assigned unique id of the API key.
        name:
          type: string
          title: Name
          description: The user-supplied label for the key.
        prefix:
          type: string
          title: Prefix
          description: Short non-secret prefix of the key (e.g. `sbd_pk_a3f4…`), used to identify which key is which.
        plaintext:
          type: string
          title: Plaintext
          description: The full secret key value. **Returned exactly once, here** — the server only retains a hash. Store it securely; it cannot be recovered.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the key was created.
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: When the key expires; null means it never expires.
      type: object
      required:
      - id
      - name
      - prefix
      - plaintext
      - created_at
      - expires_at
      title: ApiKeyCreated
      description: 'Response for `POST /api-keys`. **The `plaintext` field is returned

        exactly once and never again** — store it securely (env var, secret manager).

        Subsequent calls to GET return everything except the plaintext.'
    ErrorCode:
      type: string
      enum:
      - UNCATEGORIZED
      - AUTH_MISSING
      - AUTH_INVALID_CREDENTIAL
      - AUTH_TOKEN_EXPIRED
      - AUTH_FORBIDDEN
      - AUTH_TENANT_MISMATCH
      - VALIDATION_ERROR
      - VALIDATION_REQUIRED_CLASSIFICATION_MISSING
      - BAD_REQUEST
      - INVALID_CURSOR
      - INVALID_FILTER
      - UNSUPPORTED_OPERATION
      - PAYLOAD_TOO_LARGE
      - TENANT_NOT_FOUND
      - TENANT_SLUG_TAKEN
      - USER_NOT_FOUND
      - USER_EMAIL_TAKEN
      - INVITATION_NOT_FOUND
      - INVITATION_PENDING
      - INVITATION_NOT_PENDING
      - INVITATION_EXPIRED
      - LAST_ADMIN
      - DATASET_NOT_FOUND
      - DATASET_NAME_TAKEN
      - DATASET_DELETED
      - DATASET_ASSET_CAP_EXCEEDED
      - ASSET_NOT_FOUND
      - ASSET_DELETED
      - ASSET_NOT_EMBEDDED
      - ASSET_FORMAT_UNSUPPORTED
      - ASSET_TOO_LARGE
      - PROJECT_NOT_FOUND
      - PROJECT_ARCHIVED
      - PROJECT_MEMBER_NOT_FOUND
      - PROJECT_CLASS_NOT_FOUND
      - VERSION_NOT_FOUND
      - MODEL_NOT_FOUND
      - RESOURCE_NOT_READY
      - PROJECT_STATE_FORBIDDEN
      - CLASS_LOCKED
      - CLASS_IN_USE
      - DEPLOYMENT_NOT_FOUND
      - DEPLOYMENT_STATE_FORBIDDEN
      - EXPORT_EXPIRED
      - EXPORT_FAILED
      - ANNOTATION_NOT_FOUND
      - JOB_NOT_FOUND
      - JOB_ALREADY_RUNNING
      - JOB_PER_TENANT_CAP
      - JOB_TERMINAL
      - EMBEDDER_UNAVAILABLE
      - EMBEDDER_INVOCATION_FAILED
      - NAME_TAKEN
      - IDEMPOTENCY_REPLAY
      - CONCURRENT_MODIFICATION
      - RATE_LIMITED
      - RESOURCE_LIMIT_EXCEEDED
      - INTERNAL_ERROR
      - DEPENDENCY_UNAVAILABLE
      - MODEL_LOADING
      - MODEL_STARTING
      description: Stable error code enum. Pattern-match here, never on `message`. Adding values is non-breaking; renaming/removing is a major bump.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      description: Cognito access token
      scheme: bearer