inite-ai Keys API

openapi: 3.2.0
info:
  description: 'Generated from the zod wire contracts (`pnpm openapi:build` — scripts/build-openapi.ts); do not edit by hand. Excluded on purpose: the operator/ops surface (jobs, leases, policy, stats, maintenance, GDPR cascades), which is indexed in docs/api.md, and the MCP transport `ALL /mcp/{companyId}`, which is JSON-RPC over Streamable HTTP rather than REST — MCP clients discover it through `tools/list` (docs/mcp.md). Scopes are plain bearer-key grants, not OAuth flows — each operation states its required scope.'
  license:
    identifier: AGPL-3.0-or-later
    name: AGPL-3.0-or-later
  summary: 'The community-facing platform surface: the memory core (fact ingest, search, multi-hop, synthesize, entity and fact reads), the Domain Pack registry and tenant pack admin, the document pipeline, the external-indexer work protocol, the raw-substrate driver, the evidence substrate, and source reputation reads.'
  title: INITE Brain — Platform Keys API
  version: 2.6.0
servers:
- description: Hosted instance (placeholder — self-hosted deployments serve the same paths on their own origin).
  url: https://brain.inite.ai
security:
- bearerAuth: []
tags:
- description: 'Self-serve credentials: issue, list and revoke API keys brain verifies itself. Bounded by the calling credential — a key is never wider than its issuer — and available identically on the hosted service and a self-hosted deployment.'
  name: Keys
paths:
  /v1/keys:
    get:
      description: 'The tenant''s `companyId`, its MCP URL, and the keys visible to the caller — a user-bound credential sees the keys bound to that user, a `brain:admin` (or M2M) credential sees every key in the tenant. Secrets and hashes are never returned: a row carries a display `prefix` only. `issuableScopes` is what THIS credential may grant, and `issuingEnabled` is false on a deployment with no database-backed key store. Source: src/keys/keys.controller.ts.


        Required scope: `brain:read`.'
      operationId: listApiKeys
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyListResponse'
          description: Visible keys plus the connection values.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: List the API keys this credential can see
      tags:
      - Keys
    post:
      description: 'Mints a key brain verifies itself, returning the plaintext ONCE — it is stored only as a SHA-256 hash and cannot be recovered. The granted scopes are the requested ones intersected with what the calling credential already holds, so a key is never wider than its issuer; asking for none that the caller holds is 403. Only the four delegable scopes are accepted (`brain:read`, `brain:write`, `brain:admin`, `brain:read_pii`) — operator scopes are not mintable. A user-bound caller can only bind the key to itself. Tenants are capped at 25 live keys.


        Required scope: `brain:read`.'
      operationId: issueApiKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueKeyRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedKeyResponse'
          description: The key, shown once.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Issue an API key
      tags:
      - Keys
  /v1/keys/{id}/revoke:
    post:
      description: 'Stops the key authenticating. The row is kept (revoked, not deleted) so the history stays auditable. Returns `{revoked:false}` when the id is unknown OR belongs to another tenant or another user — deliberately indistinguishable, so the endpoint cannot be used to probe for key ids. Revocation is immediate on this pod and within 30s elsewhere (the resolution cache TTL).


        Required scope: `brain:read`.'
      operationId: revokeApiKey
      parameters:
      - description: Key id from the issuing response or a listing.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeKeyResponse'
          description: Whether a key was revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Revoke an API key
      tags:
      - Keys
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Validation failed.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The key lacks the required scope.
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or unknown bearer key.
  schemas:
    RevokeKeyResponse:
      additionalProperties: false
      properties:
        revoked:
          type: boolean
      required:
      - revoked
      type: object
    IssueKeyRequest:
      additionalProperties: false
      properties:
        circle:
          pattern: ^[A-Za-z0-9._-]{1,120}$
          type: string
        expiresInDays:
          maximum: 3650
          minimum: 1
          type: integer
        name:
          maxLength: 80
          minLength: 1
          type: string
        scopes:
          items:
            enum:
            - brain:read
            - brain:write
            - brain:admin
            - brain:read_pii
            type: string
          minItems: 1
          type: array
        userId:
          maxLength: 200
          minLength: 1
          type: string
      required:
      - name
      - scopes
      type: object
    ErrorResponse:
      description: Standard NestJS error envelope.
      properties:
        error:
          type: string
        message:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
        statusCode:
          type: integer
      required:
      - statusCode
      - message
      type: object
    ApiKeySummary:
      additionalProperties: false
      properties:
        circle:
          type: string
        createdAt:
          type: string
        createdBy:
          type: string
        expiresAt:
          type: string
        id:
          type: string
        lastUsedAt:
          type: string
        name:
          type: string
        prefix:
          type: string
        revokedAt:
          type: string
        scopes:
          items:
            type: string
          type: array
        userId:
          type: string
      required:
      - id
      - name
      - prefix
      - scopes
      type: object
    KeyListResponse:
      additionalProperties: false
      properties:
        companyId:
          type: string
        issuableScopes:
          items:
            type: string
          type: array
        issuingEnabled:
          type: boolean
        keys:
          items:
            $ref: '#/components/schemas/ApiKeySummary'
          type: array
        mcpUrl:
          type: string
      required:
      - companyId
      - mcpUrl
      - keys
      - issuingEnabled
      - issuableScopes
      type: object
    IssuedKeyResponse:
      additionalProperties: false
      properties:
        companyId:
          type: string
        key:
          type: string
        keyRecord:
          $ref: '#/components/schemas/ApiKeySummary'
        mcpUrl:
          type: string
      required:
      - key
      - companyId
      - mcpUrl
      - keyRecord
      type: object
  securitySchemes:
    bearerAuth:
      description: 'API key (`Authorization: Bearer <key>`); its SHA-256 must be registered in BRAIN_API_KEYS. Keys carry scopes (`brain:read`, `brain:write`, `brain:admin`, `brain:read_pii`, `registry:publish`, `registry:curate`, `indexer:write`) — each operation states the scope it requires. Not an OAuth flow.'
      scheme: bearer
      type: http