openapi: 3.0.3
info:
  title: naturali.ai — API Keys API
  version: 1.0.0
  description: >
    Long-lived programmatic credentials (nat_sk_…), created by a logged-in user
    and embedded in a machine (a customer backend, CI, an integration). Scoped
    to a project (default) or the whole account, plus a capability set; hashed
    at rest; the raw secret is returned exactly once, at creation or rotation.
    Interactive human clients authenticate with session JWTs instead (see the
    Auth API).
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: '{baseUrl}'
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: API Keys
    description: Create, scope, rotate and revoke nat_sk_ API keys.
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/api-keys:
    get:
      tags: [API Keys]
      summary: List API keys
      description: >
        Lists API keys accessible to the caller. A project-scoped credential
        sees only keys in its project; an account-scoped credential sees all
        keys in the account. Raw secrets are never returned.
      operationId: listApiKeys
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of API keys.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApiKeyRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags: [API Keys]
      summary: Create an API key
      description: >
        Creates an API key. When `project_id` is set the key is scoped to that
        project (the default and recommended stance); omit it for an
        account-scoped key. `capabilities` narrows the key to the operations
        whose capability it names; empty, the key reaches whatever its holder's
        membership reaches. Omitted, it is empty, or the caller's own set when
        the caller is a narrowed key. An unknown capability is `400`. The raw
        `key` (nat_sk_…) is returned only in this response.

        A narrowed key may grant only a non-empty subset of its own set: a wider
        or empty set is `403`, on update too, and so is rotating a key wider
        than it.

        A project-scoped key requires membership of that project. The key
        carries no role of its own — every request it makes resolves its
        holder's membership again — so it can never reach past what its minter
        already had. An account-scoped key requires a credential that is not
        itself confined to one project.

        A connected app cannot create keys at all: a grant is revocable and a
        key is not, so a key minted under a grant would still work after the app
        was disconnected. Reading and revoking keys stay available.
      operationId: createApiKey
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreate'
      responses:
        '201':
          description: API key created. The raw key value is only returned here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ApiKeyForbidden'
  /v1/api-keys/{api_key_id}:
    parameters:
      - $ref: '#/components/parameters/ApiKeyId'
    get:
      tags: [API Keys]
      summary: Get an API key
      description: Returns metadata for an API key. The raw secret is never returned after creation.
      operationId: getApiKey
      responses:
        '200':
          description: API key metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ApiKeyForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [API Keys]
      summary: Update an API key
      description: >
        Rename an API key or replace its capability set; the change holds from
        the key's next call. The scope (project vs account) is immutable. A
        narrowed caller may set only a non-empty subset of its own set (`403`).
      operationId: updateApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyUpdate'
      responses:
        '200':
          description: API key updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyRecord'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ApiKeyForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [API Keys]
      summary: Revoke an API key
      description: >
        Revokes an API key immediately. Subsequent use returns 401, and work
        the key started (a paused generation) calls no tool on its next step.
      operationId: deleteApiKey
      responses:
        '204':
          description: API key revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ApiKeyForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/ApiKeyRevocationUnavailable'
  /v1/api-keys/{api_key_id}:rotate:
    parameters:
      - $ref: '#/components/parameters/ApiKeyId'
    post:
      tags: [API Keys]
      summary: Rotate an API key
      description: >
        Issues a new secret for the same key record (same id, scope and
        capabilities) and invalidates the previous secret. The new raw `key`
        is returned only in this response.

        Refused for a connected app, like creation: rotation returns a raw
        secret for a key the caller need never have held, so it reaches the same
        place by another door.
      operationId: rotateApiKey
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Rotated. The new raw key value is only returned here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ApiKeyForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: >-
        A connected app's OAuth access token, issued by this API's authorization
        server (discovery: /.well-known/oauth-authorization-server). Its one scope
        carries every operation, confined to the projects the user chose when
        approving the app.
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: >-
        Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1
        or not an integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The previous page's `next_cursor`; omit it for the first page. A cursor
        this list did not issue is `400`.
      schema:
        type: string
    ApiKeyId:
      name: api_key_id
      in: path
      required: true
      description: API key public ID (key_ prefix).
      schema:
        type: string
        example: key_V1StGXR8Z5jdHi6B
  responses:
    ApiKeyRevocationUnavailable:
      description: >
        `UPSTREAM_UNAVAILABLE`: the runtime did not record the revocation, so
        the key stays live. Retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ApiKeyForbidden:
      description: Authenticated, but not permitted to act on this key, or outside a narrowed key's capabilities.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The resource does not exist (existence is not leaked).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Page:
      type: object
      description:
        One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ApiKeyRecord:
      type: object
      properties:
        id:
          type: string
          description: Public API key ID (key_ prefix).
          example: key_V1StGXR8Z5jdHi6B
        name:
          type: string
          description: "Human-readable label."
          example: CI/CD Pipeline
        key_prefix:
          type: string
          description: Leading characters of the raw key, for identification.
          example: nat_sk_a1b2c3
        scope:
          type: string
          enum: [project, account]
          description: Whether the key is scoped to one project or the whole account.
          example: project
        project_id:
          type: string
          nullable: true
          x-naturali-ref: projects
          description: The project this key is scoped to; null for account-scoped keys.
          example: proj_V1StGXR8Z5jdHi6B
        capabilities:
          type: array
          description: >
            The capabilities this key is narrowed to, each the one an operation
            needs (`<module>:<OperationId>`); a call outside them is `403`.
            Empty means the key reaches whatever its holder's membership
            reaches.
          items:
            type: string
          example: ['agents:ListAgents', 'agents:CreateSession']
        created_at:
          type: string
          format: date-time
          example: '2026-07-17T00:00:00.000Z'
        last_used_at:
          type: string
          format: date-time
          nullable: true
          description: When the key was last presented; null if never used.
          example: '2026-07-17T09:12:00.000Z'
      required: [id, name, key_prefix, scope, capabilities, created_at]
    ApiKeyCreated:
      allOf:
        - $ref: '#/components/schemas/ApiKeyRecord'
        - type: object
          required: [key]
          properties:
            key:
              type: string
              description: The raw API key value (only returned once, at creation or rotation). Use as the Bearer token.
              example: nat_sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
    ApiKeyCreate:
      type: object
      required: [name]
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          description: Key name for identification.
          example: CI/CD Pipeline
        project_id:
          type: string
          x-naturali-ref: projects
          description: Project to scope the key to. Omit for an account-scoped key.
          example: proj_V1StGXR8Z5jdHi6B
        capabilities:
          type: array
          items:
            type: string
          description: >
            Capabilities to narrow the key to. Omit for none, or for the
            caller's own set when the caller is a narrowed key.
          example: ['agents:ListAgents', 'agents:CreateSession']
    ApiKeyUpdate:
      type: object
      description: At least one field must be present. Scope is immutable.
      minProperties: 1
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          example: Renamed Key
        capabilities:
          type: array
          items:
            type: string
          description: Replace the capability set; an empty array removes the narrowing.
          example: ['agents:ListAgents']
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: >-
            Structured error. Every error response uses this shape, so `code` can
            be read without first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: '^[A-Z][A-Z0-9_]*$'
              description: >-
                Machine-readable error code, UPPER_SNAKE whether naturali or the
                runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: >-
                What to do about it, naming the routes of this API to call. For
                people and agents; it may change, so branch on `code`.
              example: >-
                Use a credential whose scope includes this action, or ask a
                project `admin` or `owner` to act; the caller's role or key
                excludes it.
            meta:
              type: object
              additionalProperties: true
              description: >-
                Structured context, such as the `resource` and `limit` of a
                `PLAN_LIMIT_REACHED`.
