Kagura AI Secrets API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Secrets API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: Secrets
  description: Zero-knowledge secret store (age ciphertext; server never decrypts)
paths:
  /api/v1/config/secrets/pubkeys:
    post:
      tags:
      - Secrets
      summary: Register Pubkey
      description: Register the caller's own age recipient pubkey (pending owner approval).
      operationId: register_pubkey_api_v1_config_secrets_pubkeys_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PubkeyRegister'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PubkeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Secrets
      summary: List Pubkeys
      description: List all recipient pubkeys in the workspace (owner/admin approval console).
      operationId: list_pubkeys_api_v1_config_secrets_pubkeys_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PubkeyResponse'
                title: Response List Pubkeys Api V1 Config Secrets Pubkeys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/pubkeys/me:
    get:
      tags:
      - Secrets
      summary: List My Pubkeys
      description: List the caller's own recipient pubkeys (e.g. to check approval status).
      operationId: list_my_pubkeys_api_v1_config_secrets_pubkeys_me_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PubkeyResponse'
                title: Response List My Pubkeys Api V1 Config Secrets Pubkeys Me Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/pubkeys/{pubkey_id}/approve:
    post:
      tags:
      - Secrets
      summary: Approve Pubkey
      description: Owner-approve a pending pubkey → active (the TOFU trust gate).
      operationId: approve_pubkey_api_v1_config_secrets_pubkeys__pubkey_id__approve_post
      parameters:
      - name: pubkey_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Pubkey Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PubkeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/pubkeys/{pubkey_id}/revoke:
    post:
      tags:
      - Secrets
      summary: Revoke Pubkey
      description: Owner-revoke a pubkey; revokes its grants and flags rotation on affected secrets.
      operationId: revoke_pubkey_api_v1_config_secrets_pubkeys__pubkey_id__revoke_post
      parameters:
      - name: pubkey_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Pubkey Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PubkeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets:
    post:
      tags:
      - Secrets
      summary: Put Secret
      description: Store a new ciphertext version + reconcile grants. Server never sees plaintext.
      operationId: put_secret_api_v1_config_secrets_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretPut'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretPutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Secrets
      summary: List Secrets
      description: List secret names + metadata. Never returns ciphertext/values.
      operationId: list_secrets_api_v1_config_secrets_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SecretMetaResponse'
                title: Response List Secrets Api V1 Config Secrets Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/audit/verify:
    get:
      tags:
      - Secrets
      summary: Verify Audit Chain
      description: 'Recompute the workspace''s secret-access audit chain and report integrity.


        Owner/admin ops surface that makes the tamper-evidence usable in-product:

        walks the append-only log id-ascending, recomputes each HMAC ``entry_hash``

        and verifies the ``prev_hash`` linkage. Returns ``valid: true`` with the head

        hash, or ``valid: false`` with the first ``broken_at`` id and ``reason``.'
      operationId: verify_audit_chain_api_v1_config_secrets_audit_verify_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditVerifyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/revoke-grant:
    post:
      tags:
      - Secrets
      summary: Revoke Grant
      description: Revoke one recipient's grant; sets rotation_needed (revoke ≠ un-share).
      operationId: revoke_grant_api_v1_config_secrets_revoke_grant_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeGrant'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretMetaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/{name}:
    delete:
      tags:
      - Secrets
      summary: Delete Secret
      description: 'Owner-only hard-delete of a secret + its versions/grants (#1153).


        Delete is **cleanup, not a security control**: it removes superseded

        ciphertext at rest but does NOT un-share a value a recipient already fetched,

        nor rotate the still-live upstream credential. Rotate the upstream key first,

        then delete (the UI confirmation warns about this). A ``delete`` entry is

        appended to the tamper-evident audit chain before removal, and the audit

        history of the deleted secret survives (the log is FK-decoupled), so

        ``audit/verify`` still passes afterwards.


        ``{name:path}`` so slash-containing names (e.g. ``cloudflare/api-token``) are

        addressable. Owner-only mirrors the pubkey trust-gate ops (approve/revoke):

        a non-owner (incl. a non-owner admin), member, or viewer is rejected 403.'
      operationId: delete_secret_api_v1_config_secrets__name__delete
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/secrets/fetch:
    post:
      tags:
      - Secrets
      summary: Fetch Secret
      description: 'Return ciphertext to a granted caller (default-deny, audit-first).


        The service writes and commits a fail-closed audit entry before the

        ciphertext is returned; a denied read raises 403 after logging. The returned

        ciphertext is opaque — the server holds no key to decrypt it.'
      operationId: fetch_secret_api_v1_config_secrets_fetch_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretFetch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretValueResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PubkeyResponse:
      properties:
        id:
          title: Id
        identity_id:
          title: Identity Id
        pubkey:
          title: Pubkey
        fingerprint:
          title: Fingerprint
        label:
          title: Label
        status:
          title: Status
        created_at:
          title: Created At
        attested_at:
          title: Attested At
        revoked_at:
          title: Revoked At
      type: object
      required:
      - id
      - identity_id
      - pubkey
      - fingerprint
      - label
      - status
      - created_at
      - attested_at
      - revoked_at
      title: PubkeyResponse
      description: Recipient pubkey metadata (the pubkey is public; no private material).
    AuditVerifyResponse:
      properties:
        valid:
          type: boolean
          title: Valid
        entries:
          anyOf:
          - type: integer
          - type: 'null'
          title: Entries
        head:
          anyOf:
          - type: string
          - type: 'null'
          title: Head
        broken_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Broken At
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        erasure_pseudonymized:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Erasure Pseudonymized
      type: object
      required:
      - valid
      title: AuditVerifyResponse
      description: Result of recomputing the workspace's tamper-evident audit chain.
    SecretPutResponse:
      properties:
        name:
          title: Name
        version_number:
          title: Version Number
        status:
          title: Status
        rotation_needed:
          title: Rotation Needed
      type: object
      required:
      - name
      - version_number
      - status
      - rotation_needed
      title: SecretPutResponse
      description: Result of a put.
    SecretValueResponse:
      properties:
        name:
          title: Name
        version_number:
          title: Version Number
        alg:
          title: Alg
        ciphertext:
          title: Ciphertext
        blob_ref:
          title: Blob Ref
        recipients_snapshot:
          title: Recipients Snapshot
        rotation_needed:
          title: Rotation Needed
        created_at:
          title: Created At
      type: object
      required:
      - name
      - version_number
      - alg
      - ciphertext
      - blob_ref
      - recipients_snapshot
      - rotation_needed
      - created_at
      title: SecretValueResponse
      description: Opaque ciphertext returned to a granted caller. The server cannot read it.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SecretMetaResponse:
      properties:
        name:
          title: Name
        status:
          title: Status
        rotation_needed:
          title: Rotation Needed
        current_version:
          title: Current Version
        grant_count:
          title: Grant Count
        created_at:
          title: Created At
        updated_at:
          title: Updated At
      type: object
      required:
      - name
      - status
      - rotation_needed
      - current_version
      - grant_count
      - created_at
      - updated_at
      title: SecretMetaResponse
      description: Secret metadata — never includes the value.
    RevokeGrant:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        recipient_pubkey_id:
          type: string
          format: uuid
          title: Recipient Pubkey Id
      type: object
      required:
      - name
      - recipient_pubkey_id
      title: RevokeGrant
      description: Revoke one recipient's grant on a secret (flags rotation_needed).
    SecretFetch:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        version_number:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Version Number
          description: Pin a version; omit for latest
      type: object
      required:
      - name
      title: SecretFetch
      description: Fetch a secret's ciphertext (name carried in body to allow '/' names).
    SecretPut:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        ciphertext:
          type: string
          maxLength: 262144
          minLength: 1
          title: Ciphertext
          description: Armored age ciphertext
        recipients_snapshot:
          items:
            type: string
          type: array
          minItems: 1
          title: Recipients Snapshot
          description: Fingerprints the ciphertext was encrypted to
        grant_pubkey_ids:
          items:
            type: string
            format: uuid
          type: array
          minItems: 1
          title: Grant Pubkey Ids
          description: Recipient pubkey ids to grant (must be active)
      type: object
      required:
      - name
      - ciphertext
      - recipients_snapshot
      - grant_pubkey_ids
      title: SecretPut
      description: Store a new ciphertext version of a secret. Server never sees plaintext.
    PubkeyRegister:
      properties:
        pubkey:
          type: string
          maxLength: 128
          minLength: 8
          title: Pubkey
          description: age recipient public key (age1…)
        label:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Label
          description: Friendly label
      type: object
      required:
      - pubkey
      title: PubkeyRegister
      description: Register the caller's own age recipient pubkey (becomes pending).