Kagura AI Member Credentials API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Member Credentials API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: member-credentials
  description: API key and OAuth credential management
paths:
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials:
    get:
      tags:
      - member-credentials
      summary: Get Member Credentials
      description: 'Get or create member credentials (Lazy initialization).


        Migration 034: Zero-knowledge model (unchanged for sessions).

        - A session caller sees plaintext ONLY for their OWN key while it is still

        visible (``get_or_create_credentials`` includes ``plaintext_key`` only

        when ``requester_id == user_id``). Session owner/admin viewing ANOTHER

        member sees metadata only.

        - Issue #1165: an API-key OWNER principal may also view another member''s key,

        but the response is ALWAYS metadata-only (``plaintext_key`` nulled) —

        programmatic responses get logged, so plaintext must never appear.

        - OAuth bearer principals are rejected (403).


        Raises:

        HTTPException: If not authorized.'
      operationId: get_member_credentials_api_v1_workspaces__workspace_id__members__user_id__credentials_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User 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/MemberCredentialsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/api-key/hide:
    post:
      tags:
      - member-credentials
      summary: Hide Api Key
      description: 'Manually hide API key (Owner only).


        Migration 034: Zero-knowledge - only owner can hide.


        Args:

        workspace_id: Workspace ID

        user_id: Target user ID

        user: Current user (from auth)

        db: Database session


        Returns:

        Status message


        Raises:

        HTTPException: If not owner or key not found'
      operationId: hide_api_key_api_v1_workspaces__workspace_id__members__user_id__credentials_api_key_hide_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Hide Api Key Api V1 Workspaces  Workspace Id  Members  User Id  Credentials Api Key Hide Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/api-key/regenerate:
    post:
      tags:
      - member-credentials
      summary: Regenerate Api Key
      description: 'Regenerate API key (Permission-based).


        Creates a replacement for the selected active workspace key and revokes it.

        Omitting ``key_id`` preserves the legacy newest-key behavior (#2379).


        New permission hierarchy:

        - Self: Always allowed

        - Owner: Can regenerate admin/member/viewer''s keys

        - Admin: Can regenerate member/viewer''s keys


        The key owner is emailed a security notice; when an admin acted, it

        names the admin (#1752).


        Args:

        workspace_id: Workspace ID

        user_id: Target user ID

        request: The request (IP / user agent for the notice)

        background_tasks: Runs the notice after the response

        user: Current user (from auth)

        db: Database session

        key_id: Public id of the selected key, or None for the legacy selection


        Returns:

        New plaintext key (shown once)


        Raises:

        HTTPException: If not authorized or key not found'
      operationId: regenerate_api_key_api_v1_workspaces__workspace_id__members__user_id__credentials_api_key_regenerate_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: key_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^akey_[0-9A-Za-z]{22}$
          - type: 'null'
          description: Public id of the key to rotate. Omit for the newest active key (legacy).
          title: Key Id
        description: Public id of the key to rotate. Omit for the newest active key (legacy).
      - 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/RegenerateAPIKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/api-keys:
    post:
      tags:
      - member-credentials
      summary: Create Api Key
      description: 'Create new API key.


        Issue #1165: two principals.

        - **Session** (web UI): self-mint only (``#252`` unchanged) — the caller

        may only mint their OWN key. ``expires_days`` is NOT accepted on this path

        (400 if supplied — session keys keep their historical no-expiry behavior);

        ``bound_context_id`` is still allowed (#626 public-bound path).

        - **API-key owner** (programmatic): may mint for ANOTHER member, gated to

        workspace-OWNER on the path workspace. Guardrails: 403 when target ==

        caller (anti self-replication, #252 threat); 403 unless the target''s

        workspace role is ``member``/``viewer`` (privilege-downgrade provisioning

        only); ``expires_days`` REQUIRED (400 if omitted — never-expiring CI keys

        are not an acceptable default); ``bound_context_id`` rejected (400 —

        public-bound keys stay self-only); the minted key is force-hidden so the

        plaintext exists only in this one 201 response.

        OAuth bearer principals are rejected (403).


        Issue #626: If ``data.bound_context_id`` is supplied, the key is stored

        as a public-bound key (``api_keys.workspace_id`` is left NULL) and is

        attributed to that one ``is_public=true`` context for the rate-limit /

        audit / revoke surface on ``/api/v1/public/{ctx}/*``. The binding is

        immutable — to change it, revoke this key and create a new one.


        Issue #2188: session self-mint takes an optional ``default_context_id``

        (the MCP default context), checked before the key is minted: 422 with a

        ``bound_context_id``, 404 ``Context not found`` when the caller cannot

        read it in the key''s workspace scope. Owner-provisioned mints reject it

        (400).


        Issue #1752: the key owner is emailed a security notice after the commit

        (naming the owner key''s user on the owner-provisioned path).


        Args:

        workspace_id: Workspace ID (from URL — used as permission scope; also

        assigned to ``api_keys.workspace_id`` unless a bound context is set)

        user_id: Target user ID

        data: API key creation data (name, auto_hide_minutes, bound_context_id,

        default_context_id)

        user: Current user (from auth)

        db: Database session


        Returns:

        Created API key with plaintext (shown once)


        Raises:

        HTTPException: If not owner, name already exists, tier gate fails,

        or the bound context is missing / not public / not in this workspace.'
      operationId: create_api_key_api_v1_workspaces__workspace_id__members__user_id__credentials_api_keys_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIKeyRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberAPIKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/api-key:
    delete:
      tags:
      - member-credentials
      summary: Delete Api Key
      description: 'Delete API key (Permission-based).


        Permission matrix:

        - Owner: Delete own key

        - Workspace Owner: Delete any member''s key

        - Workspace Admin: Delete member/viewer''s key


        Args:

        workspace_id: Workspace ID

        user_id: Target user ID

        user: Current user (from auth)

        db: Database session


        Returns:

        Status message


        Raises:

        HTTPException: If not authorized or key not found'
      operationId: delete_api_key_api_v1_workspaces__workspace_id__members__user_id__credentials_api_key_delete
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Api Key Api V1 Workspaces  Workspace Id  Members  User Id  Credentials Api Key Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/api-keys/{key_id}:
    delete:
      tags:
      - member-credentials
      summary: Delete Api Key By Id
      description: 'Delete/revoke a specific API key by its public id (``akey_...``, #1008).


        Issue #626: per-id endpoint (also revokes public-bound keys). The URL

        ``workspace_id`` is the permission scope, not a filter on the key''s column.


        Issue #1165: two principals.

        - **Session**: self-only (``#252`` unchanged) — hard delete of your own key.

        - **API-key OWNER** (programmatic): may revoke ANOTHER member''s key (target

        must be member/viewer). This is a **soft revoke** (``revoked_at=now``, row

        retained for forensics), and the audit row is written BEFORE the state

        change. OAuth bearer principals are rejected (403).


        Raises:

        HTTPException: 403 if not permitted, 404 if key not found.'
      operationId: delete_api_key_by_id_api_v1_workspaces__workspace_id__members__user_id__credentials_api_keys__key_id__delete
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          description: Public id of the API key (`akey_` + 22 base62 characters).
          examples:
          - akey_0000000000000000000000
          title: Key Id
        description: Public id of the API key (`akey_` + 22 base62 characters).
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Api Key By Id Api V1 Workspaces  Workspace Id  Members  User Id  Credentials Api Keys  Key Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/oauth/hide:
    post:
      tags:
      - member-credentials
      summary: Hide Oauth App
      description: 'Manually hide OAuth app secret (Owner only).


        Migration 034: Zero-knowledge - only owner can hide.


        Args:

        workspace_id: Workspace ID

        user_id: Target user ID

        user: Current user (from auth)

        db: Database session


        Returns:

        Status message


        Raises:

        HTTPException: If not owner or app not found'
      operationId: hide_oauth_app_api_v1_workspaces__workspace_id__members__user_id__credentials_oauth_hide_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Hide Oauth App Api V1 Workspaces  Workspace Id  Members  User Id  Credentials Oauth Hide Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/oauth/regenerate:
    post:
      tags:
      - member-credentials
      summary: Regenerate Oauth Secret
      description: 'Regenerate OAuth client secret (Permission-based).


        Migration 034: Generates new secret, updates hash.


        New permission hierarchy:

        - Self: Always allowed

        - Owner: Can regenerate admin/member/viewer''s secrets

        - Admin: Can regenerate member/viewer''s secrets


        The app owner is emailed a security notice; when an admin acted, it

        names the admin (#1752).


        Args:

        workspace_id: Workspace ID

        user_id: Target user ID

        request: The request (IP / user agent for the notice)

        background_tasks: Runs the notice after the response

        user: Current user (from auth)

        db: Database session


        Returns:

        New plaintext secret (shown once)


        Raises:

        HTTPException: If not authorized or app not found'
      operationId: regenerate_oauth_secret_api_v1_workspaces__workspace_id__members__user_id__credentials_oauth_regenerate_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User 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/RegenerateOAuthSecretResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/members/{user_id}/credentials/oauth:
    delete:
      tags:
      - member-credentials
      summary: Delete Oauth App
      description: 'Delete OAuth app (Permission-based).


        Permission matrix:

        - Owner: Delete own app

        - Workspace Owner: Delete any member''s app

        - Workspace Admin: Delete member/viewer''s app


        Args:

        workspace_id: Workspace ID

        user_id: Target user ID

        user: Current user (from auth)

        db: Database session


        Returns:

        Status message


        Raises:

        HTTPException: If not authorized or app not found'
      operationId: delete_oauth_app_api_v1_workspaces__workspace_id__members__user_id__credentials_oauth_delete
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Oauth App Api V1 Workspaces  Workspace Id  Members  User Id  Credentials Oauth Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MemberCredentialsResponse:
      properties:
        api_keys:
          items:
            $ref: '#/components/schemas/MemberAPIKeyResponse'
          type: array
          title: Api Keys
        target_user_role:
          type: string
          title: Target User Role
      type: object
      required:
      - api_keys
      - target_user_role
      title: MemberCredentialsResponse
      description: 'Response for member credentials (API Keys).


        Migration 034: Member-scoped credentials.

        Note: OAuth Apps managed via /oauth/clients API.'
    RegenerateAPIKeyResponse:
      properties:
        key:
          type: string
          title: Key
        key_prefix:
          type: string
          title: Key Prefix
        key_id:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          title: Key Id
      type: object
      required:
      - key
      - key_prefix
      - key_id
      title: RegenerateAPIKeyResponse
      description: 'Response for API key regeneration.


        Migration 034: Returns new plaintext key (shown once).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateAPIKeyRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
        auto_hide_minutes:
          type: integer
          title: Auto Hide Minutes
          default: 10
        bound_context_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Bound Context Id
        expires_days:
          anyOf:
          - type: integer
            maximum: 3650.0
            minimum: 1.0
          - type: 'null'
          title: Expires Days
        agent_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Agent Id
        default_context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Default Context Id
      type: object
      required:
      - name
      title: CreateAPIKeyRequest
      description: 'Request for creating a new API key.


        Issue #626: ``bound_context_id`` makes this a public-bound key that is

        attributed to one ``is_public=true`` context (immutable binding —

        revoke and re-create to change). Mutually exclusive with the

        workspace-scoping derived from the URL: when supplied, the key is

        stored with ``workspace_id=NULL``.'
    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
    MemberAPIKeyResponse:
      properties:
        id:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          title: Id
        name:
          type: string
          title: Name
        key_prefix:
          type: string
          title: Key Prefix
        plaintext_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Plaintext Key
        is_visible:
          type: boolean
          title: Is Visible
        visibility_expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Visibility Expires At
        created_at:
          type: string
          title: Created At
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
        revoked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked At
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
        bound_context_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Bound Context Id
        default_context_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Context Id
        default_context_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Context Name
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
        connector_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Connector Id
      type: object
      required:
      - id
      - name
      - key_prefix
      - plaintext_key
      - is_visible
      - visibility_expires_at
      - created_at
      - revoked_at
      title: MemberAPIKeyResponse
      description: 'Response for member''s API key (Zero-knowledge model).


        Migration 034: Member-scoped credentials.

        Issue #626: Optional public-context binding.'
    RegenerateOAuthSecretResponse:
      properties:
        client_secret:
          type: string
          title: Client Secret
        client_id:
          type: string
          title: Client Id
      type: object
      required:
      - client_secret
      - client_id
      title: RegenerateOAuthSecretResponse
      description: 'Response for OAuth client secret regeneration.


        Migration 034: Returns new plaintext secret (shown once).'