Monid API Keys API

openapi: 3.2.0
info:
  title: Monid API Keys API
  version: 0.1.0
  description: Agentic payment platform for data — agents discover and buy data on demand. Authenticated `/v1/*` routes accept a Monid API key or Clerk JWT as a Bearer token. All errors return `{ code, message }`. List endpoints use cursor pagination; consult each operation schema for its last-page cursor encoding.
servers:
- url: https://api.monid.ai
  description: Production
- url: https://monid.ai
  description: Public registry alias (public/v1 only)
tags:
- name: API Keys
paths:
  /v1/api-keys/scopes:
    get:
      tags:
      - API Keys
      summary: List the scope catalog
      description: Every scope an API key may hold, nested by resource with the actions a route actually requires. Static and cacheable. For what an omitted `scopes` mints for YOUR credential see `GET /v1/auth/whoami` → `credential.defaultScopes`; the most you may mint is `credential.scopes`. Requires no scope.
      security:
      - Bearer: []
      responses:
        '200':
          description: The scope catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScopeCatalog'
        '400':
          description: Bad request — input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — caller has no workspace or no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (errorCode `RATE_LIMITED`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` and `X-RateLimit-Rule` name the binding rule (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / origin / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1ApiKeysScopes
      x-operation-id-source: derived
  /v1/api-keys:
    get:
      tags:
      - API Keys
      summary: List API keys
      description: Cursor-paginated list of the workspace's API keys. Returns metadata only — the full key value is never retrievable.
      security:
      - Bearer: []
      parameters:
      - schema:
          type: integer
          exclusiveMinimum: 0
          description: Max items per page (server-side cap applies).
          example: 20
        required: false
        description: Max items per page (server-side cap applies).
        name: limit
        in: query
      - schema:
          type: string
          description: Cursor returned by the previous page.
        required: false
        description: Cursor returned by the previous page.
        name: cursor
        in: query
      - schema:
          type: string
          description: Comma-separated statuses to include (ACTIVE, EXPIRED, REVOKED). Omitted ⇒ every status except REVOKED.
          example: ACTIVE,EXPIRED
        required: false
        description: Comma-separated statuses to include (ACTIVE, EXPIRED, REVOKED). Omitted ⇒ every status except REVOKED.
        name: status
        in: query
      responses:
        '200':
          description: API keys page
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
                  cursor:
                    type: string
                    description: Opaque cursor for the next page. Absent on the last page.
                required:
                - items
        '400':
          description: Bad request — input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — caller has no workspace or no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (errorCode `RATE_LIMITED`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` and `X-RateLimit-Rule` name the binding rule (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / origin / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1ApiKeys
      x-operation-id-source: derived
  /v1/api-keys/{label}:
    get:
      tags:
      - API Keys
      summary: Get an API key
      description: Returns one live (ACTIVE or EXPIRED) key's metadata — scopes, status, expiry, who minted it. The secret is never returned. Revoked keys are not addressable by label; list with `?status=REVOKED` instead.
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Label of the API key.
          example: ci-runner
        required: true
        description: Label of the API key.
        name: label
        in: path
      responses:
        '200':
          description: The API key (metadata only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          description: Bad request — input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — caller has no workspace or no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: API key not found in this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (errorCode `RATE_LIMITED`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` and `X-RateLimit-Rule` name the binding rule (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / origin / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1ApiKeysByLabel
      x-operation-id-source: derived
    patch:
      tags:
      - API Keys
      summary: Update an API key
      description: Updates an API key's metadata (currently only the label).
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Current label of the API key.
          example: ci-runner
        required: true
        description: Current label of the API key.
        name: label
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeyRequest'
      responses:
        '200':
          description: Updated API key metadata (never the full key)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          description: Bad request — input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — caller has no workspace or no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: API key not found in this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (errorCode `RATE_LIMITED`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` and `X-RateLimit-Rule` name the binding rule (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / origin / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: patchV1ApiKeysByLabel
      x-operation-id-source: derived
  /v1/api-keys/{label}/revoke:
    post:
      tags:
      - API Keys
      summary: Revoke an API key
      description: Revokes an API key. The key stops authenticating immediately, stays listed as REVOKED for audit, and its label can be reused — so a revoked key is no longer addressable by label (404). This is the only revoke operation; there is no hard delete.
      security:
      - Bearer: []
      parameters:
      - schema:
          type: string
          minLength: 1
          description: Label of the API key to revoke.
          example: ci-runner
        required: true
        description: Label of the API key to revoke.
        name: label
        in: path
      responses:
        '200':
          description: API key revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          description: Bad request — input failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — caller has no workspace or no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: API key not found in this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (errorCode `RATE_LIMITED`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` and `X-RateLimit-Rule` name the binding rule (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / origin / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postV1ApiKeysByLabelRevoke
      x-operation-id-source: derived
components:
  schemas:
    UpdateApiKeyRequest:
      type: object
      properties:
        label:
          type: string
          minLength: 1
          description: New label for the key.
          example: ci-runner-renamed
    ScopeCatalog:
      type: object
      properties:
        resources:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
                enum:
                - runs
                - resources
                - wallet
                - topups
                - controls
                - api_keys
                example: runs
              label:
                type: string
                example: Runs
              description:
                type: string
                example: Start runs and read their results
              actions:
                type: array
                items:
                  type: object
                  properties:
                    key:
                      type: string
                      enum:
                      - read
                      - create
                      - update
                      - delete
                      example: create
                    description:
                      type: string
                      example: POST /v1/run — start a run
                  required:
                  - key
                  - description
                description: ONLY the actions some route requires for this resource — `{resource}:{action}` for any other pair is not a scope and is rejected at creation.
            required:
            - key
            - label
            - description
            - actions
      required:
      - resources
    ApiKey:
      type: object
      properties:
        label:
          type: string
          description: Human-readable label. Unique per workspace.
          example: ci-runner
        keyPrefix:
          type: string
          description: Display prefix of the key (e.g. "monid_test_a1b2c3d4...").
          example: monid_test_a1b2c3d4
        owner:
          type: string
          description: User id the key belongs to (bills to, listed under). Always a user; a child key inherits its parent's owner.
        createdBy:
          type: string
          description: 'Who minted the key — `USER#<id>` (dashboard), `API_KEY#<fingerprint>` (another key), `AEP#<did>` (AEP grant) — an actor id: `USER#<userId>` (dashboard), `API_KEY#<fingerprint>` (another key), `AEP#<did>` (an enrolled agent), `CLERK`, `SYSTEM`.'
          example: USER#user_2abc
        scopes:
          type: array
          items:
            type: string
            enum:
            - '*'
            - runs:*
            - resources:*
            - wallet:*
            - topups:*
            - controls:*
            - api_keys:*
            - runs:create
            - runs:read
            - runs:update
            - resources:read
            - resources:create
            - resources:update
            - resources:delete
            - wallet:read
            - wallet:update
            - topups:create
            - controls:read
            - controls:create
            - controls:update
            - controls:delete
            - api_keys:read
            - api_keys:create
            - api_keys:update
            - api_keys:delete
          minItems: 1
          description: 'Scope grants: `{resource}:{action}` over runs, resources, wallet, topups, controls and api_keys with read/create/update/delete, plus `{resource}:*` and `*`. Catalog reads need no scope. Fixed at creation.'
          example:
          - runs:create
          - runs:read
          - wallet:read
        status:
          type: string
          enum:
          - ACTIVE
          - EXPIRED
          - REVOKED
          description: ACTIVE, EXPIRED (derived from expiresAt) or REVOKED. Only ACTIVE keys authenticate.
        origin:
          type: string
          enum:
          - DASHBOARD
          - API
          - AEP
          - SYSTEM
          description: 'Channel the key was minted through — derived from `createdBy`: DASHBOARD, API, AEP or SYSTEM.'
        expiresAt:
          type: string
          format: date-time
          description: Expiry (ISO 8601). Absent ⇒ never expires.
        revokedAt:
          type: string
          format: date-time
          description: When the key was revoked. Present only when REVOKED.
        revokedBy:
          type: string
          description: 'Who revoked the key (present only when REVOKED) — an actor id: `USER#<userId>` (dashboard), `API_KEY#<fingerprint>` (another key), `AEP#<did>` (an enrolled agent), `CLERK`, `SYSTEM`.'
          example: USER#user_2abc
        createdAt:
          type: string
          format: date-time
          description: Creation time (ISO 8601).
        lastUsedAt:
          type: string
          format: date-time
          description: Last time the key authenticated a request. Absent if never used.
      required:
      - label
      - keyPrefix
      - owner
      - createdBy
      - scopes
      - status
      - origin
      - createdAt
    Error:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code, duplicated in the body.
          example: 400
        message:
          type: string
          description: Human-readable error description.
          example: Bad Request
        errorCode:
          type: string
          enum:
          - RATE_LIMITED
          - X402_WORKSPACE_RESOURCES
          - X402_ACCRUING_COST
          - X402_EXCEEDS_SETTLEMENT_WINDOW
          - X402_VALIDITY_WINDOW_TOO_SHORT
          - X402_UNBOUNDED_PRICE
          - INSUFFICIENT_SCOPE
          - WALLET_INSUFFICIENT_FUNDS
          - IDENTITY_PROVIDER_UNKNOWN
          - IDENTITY_LINK_REQUIRES_SESSION
          - IDENTITY_LINK_STATE_INVALID
          - IDENTITY_VERIFICATION_FAILED
          - IDENTITY_PROVIDER_UNAVAILABLE
          - IDENTITY_ALREADY_LINKED
          - IDENTITY_USER_ALREADY_LINKED
          - IDENTITY_LINK_RATE_LIMITED
          - IDENTITY_REQUIRED
          - PROMO_IDENTITY_REDEEMED
          - PROMO_REDEEM_REQUIRES_SESSION
          - PROMO_REDEEM_DISABLED
          description: OPTIONAL machine-readable discriminant from the documented `ApiErrorCode` registry. Absent on legacy errors; clients MUST treat unknown values as absent.
      required:
      - code
      - message
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: 'Monid API key (`Authorization: Bearer mk_...`) or Clerk-issued JWT.'