openapi.yaml

# yaml-language-server: $schema=https://spec.openapis.org/oas/3.1/schema/2022-10-07
openapi: 3.1.0
info:
  title: InferaDB Control
  description: |
    Multi-tenant administration API for InferaDB. Manages organizations, users,
    vaults, clients, schemas, and token issuance.

    ## Authentication

    Control uses JWT Bearer tokens for API authentication. Obtain tokens via:

    - **Email code flow**: Passwordless authentication (initiate → verify → complete)
    - **Passkey (WebAuthn)**: FIDO2 authentication with hardware keys
    - **Client assertion**: RFC 7523 JWT Bearer grant for machine-to-machine auth

    Include the token in the `Authorization` header: `Authorization: Bearer <token>`.

    Read endpoints use locally-validated JWTs (Ed25519). Write endpoints validate
    tokens against the Ledger backend.

    ## Rate limiting

    - Login endpoints: 100 requests/hour per IP
    - Registration: 5 requests/day per IP

    Rate-limited responses return `429 Too Many Requests` with a `Retry-After` header.

    ## Pagination

    List endpoints use cursor-based pagination with `page_size` (default 50, max 100)
    and `page_token` query parameters. Responses include `next_page_token` when more
    results are available.

    ## Errors

    All error responses use the format: `{"error": "message", "code": "ERROR_CODE"}`.
  version: 0.1.0
  contact:
    name: InferaDB
    url: https://inferadb.com
    email: open@inferadb.com
  license:
    name: MIT OR Apache-2.0
    url: https://github.com/inferadb/control/blob/main/LICENSE-MIT

servers:
  - url: http://localhost:9090
    description: Local development

tags:
  - name: Email auth
    description: Passwordless email code authentication
  - name: Session
    description: Token refresh, logout, and session revocation
  - name: MFA
    description: TOTP, recovery codes, and passkey authentication
  - name: Passkey registration
    description: Register passkey credentials for the authenticated user
  - name: Users
    description: User profile management
  - name: Emails
    description: User email address management
  - name: Organizations
    description: Multi-tenant organization management
  - name: Members
    description: Organization membership management
  - name: Invitations
    description: Organization invitations
  - name: Teams
    description: Team management within organizations
  - name: Team members
    description: Team membership management
  - name: Clients
    description: API client (application) management
  - name: Certificates
    description: Client certificate lifecycle
  - name: Vaults
    description: Vault management within organizations
  - name: Schemas
    description: Vault schema versioning and deployment
  - name: Tokens
    description: Vault-scoped JWT generation and refresh
  - name: Audit logs
    description: Organization audit log querying
  - name: Health
    description: Health check and monitoring endpoints

paths:
  # ── Email Auth ───────────────────────────────────────────────────────

  /control/v1/auth/email/initiate:
    post:
      tags: [Email auth]
      summary: Send a verification code
      description: Sends a one-time verification code to the provided email address.
      operationId: emailInitiate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                  example: alice@northwind.com
                region:
                  type: string
                  description: Preferred region for new account creation.
                  example: us-east-va
      responses:
        "200":
          description: Verification code sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: verification code sent
        "400":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  /control/v1/auth/email/verify:
    post:
      tags: [Email auth]
      summary: Verify email code
      description: |
        Validates the verification code. Returns one of three outcomes:
        - `authenticated`: Existing user, returns token pair
        - `totp_required`: User has TOTP enabled, returns challenge nonce
        - `registration_required`: New user, returns onboarding token
      operationId: emailVerify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, code]
              properties:
                email:
                  type: string
                  format: email
                code:
                  type: string
                  example: "123456"
                region:
                  type: string
      responses:
        "200":
          description: Verification result (discriminated by `status` field).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/VerifyAuthenticated"
                  - $ref: "#/components/schemas/VerifyTotpRequired"
                  - $ref: "#/components/schemas/VerifyRegistrationRequired"
              examples:
                authenticated:
                  value:
                    status: authenticated
                    access_token: eyJ...
                    refresh_token: rt_abc123
                    token_type: Bearer
                totp_required:
                  value:
                    status: totp_required
                    challenge_nonce: base64-encoded-nonce
                registration_required:
                  value:
                    status: registration_required
                    onboarding_token: ilobt_abc123
        "400":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  /control/v1/auth/email/complete:
    post:
      tags: [Email auth]
      summary: Complete registration
      description: Creates a new user account and organization. Requires a valid onboarding token from the verify step.
      operationId: emailComplete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [onboarding_token, email, name, organization_name]
              properties:
                onboarding_token:
                  type: string
                email:
                  type: string
                  format: email
                name:
                  type: string
                  example: Alice Chen
                organization_name:
                  type: string
                  example: Northwind Analytics
                region:
                  type: string
      responses:
        "200":
          description: Registration complete. Returns token pair and resource slugs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  registration:
                    type: object
                    properties:
                      user:
                        type: integer
                        format: uint64
                      organization:
                        type: integer
                        format: uint64
                      access_token:
                        type: string
                      refresh_token:
                        type: string
                      token_type:
                        type: string
                        example: Bearer
        "400":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  # ── Session ──────────────────────────────────────────────────────────

  /control/v1/auth/refresh:
    post:
      tags: [Session]
      summary: Refresh session tokens
      description: Exchange a refresh token for a new access/refresh token pair. The refresh token can be sent in the request body or via the `inferadb_refresh` cookie.
      operationId: refreshSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: Omit if using the refresh cookie.
      responses:
        "200":
          description: New token pair.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionTokenResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/auth/logout:
    post:
      tags: [Session]
      summary: Log out
      description: Clears session cookies. Always succeeds.
      operationId: logout
      responses:
        "200":
          description: Logged out.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: logged out

  /control/v1/auth/revoke-all:
    post:
      tags: [Session]
      summary: Revoke all sessions
      description: Revokes all refresh tokens for the authenticated user.
      operationId: revokeAll
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Sessions revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked_count:
                    type: integer
                    format: uint64
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── MFA ──────────────────────────────────────────────────────────────

  /control/v1/auth/totp/verify:
    post:
      tags: [MFA]
      summary: Verify TOTP code
      description: Completes authentication with a TOTP code after the email verify step returned `totp_required`.
      operationId: verifyTotp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_slug, totp_code, challenge_nonce]
              properties:
                user_slug:
                  type: integer
                  format: uint64
                totp_code:
                  type: string
                  example: "123456"
                challenge_nonce:
                  type: string
                  format: base64
      responses:
        "200":
          description: Authentication successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionTokenResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  /control/v1/auth/recovery:
    post:
      tags: [MFA]
      summary: Use a recovery code
      description: Authenticates with a one-time recovery code. Returns the number of remaining codes.
      operationId: consumeRecovery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_slug, code, challenge_nonce]
              properties:
                user_slug:
                  type: integer
                  format: uint64
                code:
                  type: string
                  example: ABCD-1234
                challenge_nonce:
                  type: string
                  format: base64
      responses:
        "200":
          description: Authentication successful.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SessionTokenResponse"
                  - type: object
                    properties:
                      remaining_codes:
                        type: integer
                        format: uint32
        "400":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  /control/v1/auth/passkey/begin:
    post:
      tags: [MFA]
      summary: Begin passkey authentication
      description: Initiates a WebAuthn authentication ceremony. Returns a challenge for the client to sign.
      operationId: passkeyBegin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_slug]
              properties:
                user_slug:
                  type: integer
                  format: uint64
      responses:
        "200":
          description: Authentication challenge.
          content:
            application/json:
              schema:
                type: object
                properties:
                  challenge_id:
                    type: string
                  challenge:
                    type: object
                    description: WebAuthn PublicKeyCredentialRequestOptions.
        "429":
          $ref: "#/components/responses/RateLimited"

  /control/v1/auth/passkey/finish:
    post:
      tags: [MFA]
      summary: Complete passkey authentication
      description: Completes the WebAuthn authentication ceremony with the signed credential.
      operationId: passkeyFinish
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [challenge_id, credential]
              properties:
                challenge_id:
                  type: string
                credential:
                  type: object
                  description: WebAuthn PublicKeyCredential response.
      responses:
        "200":
          description: Authentication result.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/VerifyAuthenticated"
                  - $ref: "#/components/schemas/VerifyTotpRequired"
        "400":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  # ── Email verification ───────────────────────────────────────────────

  /control/v1/auth/verify-email:
    post:
      tags: [Emails]
      summary: Verify an email address
      description: Confirms an email address using a verification token sent via email.
      operationId: verifyEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
      responses:
        "200":
          description: Email verified.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  verified:
                    type: boolean
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Passkey Registration ─────────────────────────────────────────────

  /control/v1/users/me/credentials/passkeys/begin:
    post:
      tags: [Passkey registration]
      summary: Begin passkey registration
      description: Starts a WebAuthn registration ceremony for the authenticated user.
      operationId: passkeyRegisterBegin
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Human-readable label for the credential.
                  example: MacBook Pro
      responses:
        "200":
          description: Registration challenge.
          content:
            application/json:
              schema:
                type: object
                properties:
                  challenge_id:
                    type: string
                  challenge:
                    type: object
                    description: WebAuthn PublicKeyCredentialCreationOptions.
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/users/me/credentials/passkeys/finish:
    post:
      tags: [Passkey registration]
      summary: Complete passkey registration
      description: Completes the WebAuthn registration ceremony and stores the credential.
      operationId: passkeyRegisterFinish
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [challenge_id, name, credential]
              properties:
                challenge_id:
                  type: string
                name:
                  type: string
                  example: MacBook Pro
                credential:
                  type: object
                  description: WebAuthn RegisterPublicKeyCredential response.
      responses:
        "200":
          description: Credential registered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: integer
                    format: uint64
                  name:
                    type: string
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Users ────────────────────────────────────────────────────────────

  /control/v1/users/me:
    get:
      tags: [Users]
      summary: Get your profile
      operationId: getProfile
      security:
        - BearerAuth: []
      responses:
        "200":
          description: User profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: "#/components/schemas/UserProfile"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags: [Users]
      summary: Update your profile
      operationId: updateProfile
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Alice Chen
      responses:
        "200":
          description: Updated profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: "#/components/schemas/UserProfile"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Users]
      summary: Delete your account
      operationId: deleteUser
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Account deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Emails ───────────────────────────────────────────────────────────

  /control/v1/users/emails:
    get:
      tags: [Emails]
      summary: List your email addresses
      operationId: listEmails
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Email addresses.
          content:
            application/json:
              schema:
                type: object
                properties:
                  emails:
                    type: array
                    items:
                      $ref: "#/components/schemas/EmailInfo"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Emails]
      summary: Add an email address
      operationId: addEmail
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        "200":
          description: Email added (verification pending).
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    $ref: "#/components/schemas/EmailInfo"
                  message:
                    type: string
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/users/emails/{id}:
    delete:
      tags: [Emails]
      summary: Remove an email address
      operationId: deleteEmail
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/EmailId"
      responses:
        "200":
          description: Email removed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Organizations ────────────────────────────────────────────────────

  /control/v1/organizations:
    get:
      tags: [Organizations]
      summary: List your organizations
      operationId: listOrganizations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Organizations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      $ref: "#/components/schemas/Organization"
                  next_page_token:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Organizations]
      summary: Create an organization
      operationId: createOrganization
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  example: Northwind Analytics
      responses:
        "201":
          description: Organization created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: "#/components/schemas/Organization"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}:
    get:
      tags: [Organizations]
      summary: Get an organization
      operationId: getOrganization
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      responses:
        "200":
          description: Organization details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: "#/components/schemas/Organization"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    patch:
      tags: [Organizations]
      summary: Update an organization
      operationId: updateOrganization
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "200":
          description: Updated organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: "#/components/schemas/Organization"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Organizations]
      summary: Delete an organization
      operationId: deleteOrganization
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      responses:
        "200":
          description: Organization deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Members ──────────────────────────────────────────────────────────

  /control/v1/organizations/{org}/members:
    get:
      tags: [Members]
      summary: List organization members
      operationId: listMembers
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: "#/components/schemas/Member"
                  next_page_token:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/members/{member}:
    patch:
      tags: [Members]
      summary: Update a member's role
      operationId: updateMemberRole
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/MemberSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role:
                  type: string
                  enum: [admin, member]
      responses:
        "200":
          description: Role updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  member:
                    $ref: "#/components/schemas/Member"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "403":
          $ref: "#/components/responses/AuthorizationError"
    delete:
      tags: [Members]
      summary: Remove a member
      operationId: removeMember
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/MemberSlug"
      responses:
        "200":
          description: Member removed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "403":
          $ref: "#/components/responses/AuthorizationError"

  /control/v1/organizations/{org}/members/me:
    delete:
      tags: [Members]
      summary: Leave an organization
      operationId: leaveOrganization
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      responses:
        "200":
          description: Left organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Invitations ──────────────────────────────────────────────────────

  /control/v1/organizations/{org}/invitations:
    get:
      tags: [Invitations]
      summary: List organization invitations
      operationId: listInvitations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Invitations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    items:
                      $ref: "#/components/schemas/Invitation"
                  next_page_token:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Invitations]
      summary: Invite a user to the organization
      operationId: createInvitation
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum: [admin, member]
                  description: Defaults to member.
      responses:
        "201":
          description: Invitation created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invitation"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/invitations/{invitation}:
    delete:
      tags: [Invitations]
      summary: Cancel an invitation
      operationId: deleteInvitation
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/InvitationSlug"
      responses:
        "200":
          description: Invitation cancelled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  /control/v1/users/me/invitations:
    get:
      tags: [Invitations]
      summary: List your received invitations
      operationId: listReceivedInvitations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Received invitations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invitations:
                    type: array
                    items:
                      $ref: "#/components/schemas/ReceivedInvitation"
                  next_page_token:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/users/me/invitations/{invitation}/accept:
    post:
      tags: [Invitations]
      summary: Accept an invitation
      operationId: acceptInvitation
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/InvitationSlug"
      responses:
        "200":
          description: Invitation accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  /control/v1/users/me/invitations/{invitation}/decline:
    post:
      tags: [Invitations]
      summary: Decline an invitation
      operationId: declineInvitation
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/InvitationSlug"
      responses:
        "200":
          description: Invitation declined.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Teams ────────────────────────────────────────────────────────────

  /control/v1/organizations/{org}/teams:
    get:
      tags: [Teams]
      summary: List teams
      operationId: listTeams
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Teams.
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: "#/components/schemas/Team"
                  next_page_token:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Teams]
      summary: Create a team
      operationId: createTeam
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  example: Engineering
      responses:
        "201":
          description: Team created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: "#/components/schemas/Team"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/teams/{team}:
    get:
      tags: [Teams]
      summary: Get a team
      operationId: getTeam
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
      responses:
        "200":
          description: Team details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: "#/components/schemas/Team"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      tags: [Teams]
      summary: Update a team
      operationId: updateTeam
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "200":
          description: Updated team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: "#/components/schemas/Team"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      tags: [Teams]
      summary: Delete a team
      operationId: deleteTeam
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                move_members_to:
                  type: integer
                  format: uint64
                  description: Team slug to move members to before deletion.
      responses:
        "200":
          description: Team deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Team Members ─────────────────────────────────────────────────────

  /control/v1/organizations/{org}/teams/{team}/members:
    get:
      tags: [Team members]
      summary: List team members
      operationId: listTeamMembers
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
      responses:
        "200":
          description: Team members.
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: "#/components/schemas/TeamMember"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Team members]
      summary: Add a team member
      operationId: addTeamMember
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user]
              properties:
                user:
                  type: integer
                  format: uint64
                role:
                  type: string
                  enum: [manager, member]
                  default: member
      responses:
        "200":
          description: Member added. Returns updated team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: "#/components/schemas/Team"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/teams/{team}/members/{member}:
    patch:
      tags: [Team members]
      summary: Update a team member's role
      operationId: updateTeamMember
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
        - $ref: "#/components/parameters/MemberSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role:
                  type: string
                  enum: [manager, member]
      responses:
        "200":
          description: Role updated. Returns updated team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: "#/components/schemas/Team"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Team members]
      summary: Remove a team member
      operationId: removeTeamMember
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/TeamSlug"
        - $ref: "#/components/parameters/MemberSlug"
      responses:
        "200":
          description: Member removed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Clients ──────────────────────────────────────────────────────────

  /control/v1/organizations/{org}/clients:
    get:
      tags: [Clients]
      summary: List clients
      operationId: listClients
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      responses:
        "200":
          description: Clients.
          content:
            application/json:
              schema:
                type: object
                properties:
                  clients:
                    type: array
                    items:
                      $ref: "#/components/schemas/Client"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Clients]
      summary: Create a client
      operationId: createClient
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  example: Payment Service
                description:
                  type: string
      responses:
        "201":
          description: Client created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  client:
                    $ref: "#/components/schemas/Client"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/clients/{client}:
    get:
      tags: [Clients]
      summary: Get a client
      operationId: getClient
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
      responses:
        "200":
          description: Client details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  client:
                    $ref: "#/components/schemas/Client"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    patch:
      tags: [Clients]
      summary: Update a client
      operationId: updateClient
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        "200":
          description: Updated client.
          content:
            application/json:
              schema:
                type: object
                properties:
                  client:
                    $ref: "#/components/schemas/Client"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Clients]
      summary: Delete a client
      operationId: deleteClient
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
      responses:
        "200":
          description: Client deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Certificates ─────────────────────────────────────────────────────

  /control/v1/organizations/{org}/clients/{client}/certificates:
    get:
      tags: [Certificates]
      summary: List certificates
      operationId: listCertificates
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
      responses:
        "200":
          description: Certificates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  certificates:
                    type: array
                    items:
                      $ref: "#/components/schemas/Certificate"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Certificates]
      summary: Create a certificate
      operationId: createCertificate
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, expires_at]
              properties:
                name:
                  type: string
                  example: prod-2026
                expires_at:
                  type: string
                  format: date-time
      responses:
        "201":
          description: Certificate created. The `private_key_pem` is returned only once.
          content:
            application/json:
              schema:
                type: object
                properties:
                  certificate:
                    $ref: "#/components/schemas/Certificate"
                  private_key_pem:
                    type: string
                    description: Ed25519 private key in PEM format. Store securely — not retrievable later.
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/clients/{client}/certificates/{cert}:
    get:
      tags: [Certificates]
      summary: Get a certificate
      operationId: getCertificate
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
        - $ref: "#/components/parameters/CertSlug"
      responses:
        "200":
          description: Certificate details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Certificate"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Certificates]
      summary: Revoke a certificate
      operationId: revokeCertificate
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
        - $ref: "#/components/parameters/CertSlug"
      responses:
        "200":
          description: Certificate revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/clients/{client}/secret/rotate:
    post:
      tags: [Certificates]
      summary: Rotate client secret
      operationId: rotateClientSecret
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/ClientSlug"
      responses:
        "200":
          description: New client secret. Store securely — not retrievable later.
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Vaults ───────────────────────────────────────────────────────────

  /control/v1/organizations/{org}/vaults:
    get:
      tags: [Vaults]
      summary: List vaults
      operationId: listVaults
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Vaults.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vaults:
                    type: array
                    items:
                      $ref: "#/components/schemas/Vault"
                  next_page_token:
                    type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Vaults]
      summary: Create a vault
      operationId: createVault
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
      responses:
        "201":
          description: Vault created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vault:
                    $ref: "#/components/schemas/Vault"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/vaults/{vault}:
    get:
      tags: [Vaults]
      summary: Get a vault
      operationId: getVault
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      responses:
        "200":
          description: Vault details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  vault:
                    $ref: "#/components/schemas/Vault"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    patch:
      tags: [Vaults]
      summary: Update a vault
      operationId: updateVault
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                retention_policy:
                  type: string
      responses:
        "200":
          description: Vault updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Vaults]
      summary: Delete a vault
      operationId: deleteVault
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      responses:
        "200":
          description: Vault deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessageResponse"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Schemas ──────────────────────────────────────────────────────────

  /control/v1/organizations/{org}/vaults/{vault}/schemas:
    get:
      tags: [Schemas]
      summary: List schema versions
      operationId: listSchemas
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      responses:
        "200":
          description: Schema versions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemas:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          type: integer
                          format: uint32
                        has_definition:
                          type: boolean
                        is_active:
                          type: boolean
        "401":
          $ref: "#/components/responses/AuthenticationError"
    post:
      tags: [Schemas]
      summary: Deploy a schema
      operationId: deploySchema
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [definition]
              properties:
                definition:
                  type: object
                  description: Schema definition JSON.
                version:
                  type: integer
                  format: uint32
                  description: Explicit version number. Auto-incremented if omitted.
                description:
                  type: string
      responses:
        "201":
          description: Schema deployed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaStatus"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/vaults/{vault}/schemas/current:
    get:
      tags: [Schemas]
      summary: Get the active schema
      operationId: getCurrentSchema
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      responses:
        "200":
          description: Active schema definition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaDefinition"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  /control/v1/organizations/{org}/vaults/{vault}/schemas/diff:
    get:
      tags: [Schemas]
      summary: Diff two schema versions
      operationId: diffSchemas
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
        - name: from
          in: query
          required: true
          schema:
            type: integer
            format: uint32
        - name: to
          in: query
          required: true
          schema:
            type: integer
            format: uint32
      responses:
        "200":
          description: Schema diff.
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: integer
                    format: uint32
                  to:
                    type: integer
                    format: uint32
                  changes:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        change_type:
                          type: string
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/organizations/{org}/vaults/{vault}/schemas/{version}:
    get:
      tags: [Schemas]
      summary: Get a specific schema version
      operationId: getSchema
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
        - name: version
          in: path
          required: true
          schema:
            type: integer
            format: uint32
      responses:
        "200":
          description: Schema definition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaDefinition"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  /control/v1/organizations/{org}/vaults/{vault}/schemas/{version}/activate:
    post:
      tags: [Schemas]
      summary: Activate a schema version
      operationId: activateSchema
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
        - name: version
          in: path
          required: true
          schema:
            type: integer
            format: uint32
      responses:
        "200":
          description: Schema activated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaStatus"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "404":
          $ref: "#/components/responses/NotFound"

  /control/v1/organizations/{org}/vaults/{vault}/schemas/rollback:
    post:
      tags: [Schemas]
      summary: Rollback to a previous schema version
      operationId: rollbackSchema
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      responses:
        "200":
          description: Schema rolled back.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaStatus"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Tokens ───────────────────────────────────────────────────────────

  /control/v1/organizations/{org}/vaults/{vault}/tokens:
    post:
      tags: [Tokens]
      summary: Generate a vault token
      description: Issues a vault-scoped JWT for the specified application.
      operationId: generateVaultToken
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [app]
              properties:
                app:
                  type: integer
                  format: uint64
                  description: Client (application) slug.
                scopes:
                  type: array
                  items:
                    type: string
                  default: []
      responses:
        "201":
          description: Token pair.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenPair"
        "401":
          $ref: "#/components/responses/AuthenticationError"
    delete:
      tags: [Tokens]
      summary: Revoke vault tokens
      description: Revokes all tokens for a specific application in this vault.
      operationId: revokeVaultTokens
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/VaultSlug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [app]
              properties:
                app:
                  type: integer
                  format: uint64
      responses:
        "200":
          description: Tokens revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked_count:
                    type: integer
                    format: uint64
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/tokens/refresh:
    post:
      tags: [Tokens]
      summary: Refresh a vault token
      operationId: refreshVaultToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token:
                  type: string
      responses:
        "200":
          description: New token pair.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenPair"
        "401":
          $ref: "#/components/responses/AuthenticationError"

  /control/v1/token:
    post:
      tags: [Tokens]
      summary: Client assertion authentication
      description: |
        Machine-to-machine authentication using RFC 7523 JWT Bearer grant.
        The client signs a JWT assertion with its Ed25519 private key.
      operationId: clientAssertionAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [grant_type, client_assertion_type, client_assertion, organization, vault]
              properties:
                grant_type:
                  type: string
                  enum: ["urn:ietf:params:oauth:grant-type:jwt-bearer"]
                client_assertion_type:
                  type: string
                  enum: ["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"]
                client_assertion:
                  type: string
                  description: Signed JWT assertion.
                organization:
                  type: integer
                  format: uint64
                vault:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                  default: []
                requested_role:
                  type: string
      responses:
        "201":
          description: Token pair.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenPair"
        "401":
          $ref: "#/components/responses/AuthenticationError"
        "429":
          $ref: "#/components/responses/RateLimited"

  # ── Audit Logs ───────────────────────────────────────────────────────

  /control/v1/organizations/{org}/audit-logs:
    get:
      tags: [Audit logs]
      summary: Query audit logs
      operationId: listAuditLogs
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/OrgSlug"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - name: event_type
          in: query
          schema:
            type: string
          description: Filter by event type prefix (e.g., `ledger.vault`).
        - name: principal
          in: query
          schema:
            type: string
          description: Filter by principal identifier.
        - name: outcome
          in: query
          schema:
            type: string
          description: Filter by outcome (e.g., `success`, `failure`).
      responses:
        "200":
          description: Audit log entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      $ref: "#/components/schemas/AuditLogEntry"
                  next_page_token:
                    type: string
                  total_estimate:
                    type: integer
                    format: uint64
        "401":
          $ref: "#/components/responses/AuthenticationError"

  # ── Health ───────────────────────────────────────────────────────────

  /healthz:
    get:
      tags: [Health]
      summary: Health check
      operationId: healthz
      responses:
        "200":
          description: Service health.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /livez:
    get:
      tags: [Health]
      summary: Liveness probe
      operationId: livez
      responses:
        "200":
          description: Service is alive.

  /readyz:
    get:
      tags: [Health]
      summary: Readiness probe
      operationId: readyz
      responses:
        "200":
          description: Service is ready.
        "503":
          description: Service is not ready.

  /startupz:
    get:
      tags: [Health]
      summary: Startup probe
      operationId: startupz
      responses:
        "200":
          description: Service has started.
        "503":
          description: Service is still starting.

  /metrics:
    get:
      tags: [Health]
      summary: Prometheus metrics
      operationId: metrics
      responses:
        "200":
          description: Prometheus text exposition format.
          content:
            text/plain:
              schema:
                type: string

# ── Components ───────────────────────────────────────────────────────

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Ed25519-signed JWT access token.

  parameters:
    OrgSlug:
      name: org
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Organization slug.

    VaultSlug:
      name: vault
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Vault slug.

    TeamSlug:
      name: team
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Team slug.

    ClientSlug:
      name: client
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Client (application) slug.

    CertSlug:
      name: cert
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Certificate slug.

    MemberSlug:
      name: member
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Member (user) slug.

    InvitationSlug:
      name: invitation
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Invitation slug.

    EmailId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: uint64
      description: Email address slug.

    PageSize:
      name: page_size
      in: query
      schema:
        type: integer
        format: uint32
        default: 50
        minimum: 1
        maximum: 100
      description: Number of results per page.

    PageToken:
      name: page_token
      in: query
      schema:
        type: string
      description: Opaque cursor from a previous response's `next_page_token`.

  schemas:
    SessionTokenResponse:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
          example: Bearer

    TokenPair:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          format: uint64
          description: Token lifetime in seconds.

    MessageResponse:
      type: object
      properties:
        message:
          type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: |
            Machine-readable error code. Values: `AUTHENTICATION_ERROR`,
            `AUTHORIZATION_ERROR`, `VALIDATION_ERROR`, `NOT_FOUND`,
            `ALREADY_EXISTS`, `RATE_LIMIT_EXCEEDED`, `TIER_LIMIT_EXCEEDED`,
            `TOO_MANY_PASSKEYS`, `SERVICE_UNAVAILABLE`, `EXTERNAL_SERVICE_ERROR`,
            `INTERNAL_ERROR`, `CONFIGURATION_ERROR`, `STORAGE_ERROR`.

    VerifyAuthenticated:
      type: object
      properties:
        status:
          type: string
          enum: [authenticated]
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string

    VerifyTotpRequired:
      type: object
      properties:
        status:
          type: string
          enum: [totp_required]
        challenge_nonce:
          type: string

    VerifyRegistrationRequired:
      type: object
      properties:
        status:
          type: string
          enum: [registration_required]
        onboarding_token:
          type: string

    UserProfile:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        name:
          type: string
        status:
          type: string
        role:
          type: string
        created_at:
          type: string
          format: date-time

    EmailInfo:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        email:
          type: string
          format: email
        verified:
          type: boolean
        created_at:
          type: string
          format: date-time
        verified_at:
          type: string
          format: date-time

    Organization:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        name:
          type: string
        region:
          type: string
        status:
          type: string
        tier:
          type: string

    Member:
      type: object
      properties:
        user:
          type: integer
          format: uint64
        role:
          type: string
        joined_at:
          type: string
          format: date-time

    Invitation:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        organization:
          type: integer
          format: uint64
        inviter:
          type: integer
          format: uint64
        invitee_email:
          type: string
          format: email
        role:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    ReceivedInvitation:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        organization:
          type: integer
          format: uint64
        organization_name:
          type: string
        role:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    Team:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        organization:
          type: integer
          format: uint64
        name:
          type: string
        members:
          type: array
          items:
            $ref: "#/components/schemas/TeamMember"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    TeamMember:
      type: object
      properties:
        user:
          type: integer
          format: uint64
        role:
          type: string
          enum: [manager, member]
        joined_at:
          type: string
          format: date-time

    Client:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        name:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        credentials:
          type: object
          properties:
            client_secret_enabled:
              type: boolean
            mtls_ca_enabled:
              type: boolean
            mtls_self_signed_enabled:
              type: boolean
            client_assertion_enabled:
              type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Certificate:
      type: object
      properties:
        slug:
          type: integer
          format: uint64
        name:
          type: string
        enabled:
          type: boolean
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time

    Vault:
      type: object
      properties:
        organization:
          type: integer
          format: uint64
        slug:
          type: integer
          format: uint64
        height:
          type: integer
          format: uint64
        status:
          type: string
        nodes:
          type: array
          items:
            type: string
        leader:
          type: string

    SchemaStatus:
      type: object
      properties:
        version:
          type: integer
          format: uint32
        status:
          type: string

    SchemaDefinition:
      type: object
      properties:
        version:
          type: integer
          format: uint32
        definition:
          type: object
        description:
          type: string

    AuditLogEntry:
      type: object
      properties:
        event_id:
          type: string
        event_type:
          type: string
        principal:
          type: string
        outcome:
          type: string
        timestamp:
          type: string
          format: date-time
        source:
          type: string
        action:
          type: string
        details:
          type: object
          additionalProperties:
            type: string

    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [healthy, degraded, unhealthy]
        service:
          type: string
          example: inferadb-control
        version:
          type: string
        instance_id:
          type: integer
          format: uint16
        uptime_seconds:
          type: integer
          format: uint64
        ledger_healthy:
          type: boolean
        details:
          type: string

  responses:
    ValidationError:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: invalid email address
            code: VALIDATION_ERROR

    AuthenticationError:
      description: Authentication required or token invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: authentication required
            code: AUTHENTICATION_ERROR

    AuthorizationError:
      description: Insufficient permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: insufficient permissions
            code: AUTHORIZATION_ERROR

    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: not found
            code: NOT_FOUND

    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the rate limit resets.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: rate limit exceeded
            code: RATE_LIMIT_EXCEEDED