Kagura AI Account Linking API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Account Linking API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: account-linking
  description: 'Sign-in providers: attach, detach and list the external login providers (Google, GitHub) of the current account — several ways to sign in to ONE account. Not to be confused with identity-links.'
paths:
  /api/v1/me/account/link-provider:
    post:
      tags:
      - account-linking
      summary: Link Provider
      description: 'Attach a sign-in provider to the current account: start a link-mode

        OAuth round-trip. This adds a way to sign in to ONE account; counting two

        accounts as one owner is an identity link (``/identity-links``).


        The account is proved first, with the policy of passkey registration

        (``passkeys._prove``): the current password, a passkey whose challenge

        was issued for ``link:`` in this browser session, or a verified

        sign-in of this session within the last five minutes. Only then is the

        ``state`` written; it lives ``STATE_TTL`` seconds and carries the proof to

        the callback. The existing ``/auth/{provider}/callback`` reads

        ``oauth2_state_intent:{state}`` == ``"link"`` (deleting every link key on

        first read) and binds the returned identity to

        ``oauth2_state_user:{state}`` via ``AccountLinkingService`` — only when

        the callback arrives with the session cookie pinned under

        ``oauth2_state_session:{state}`` here, so the ``authorization_url`` is of

        no use to any other browser.


        Returns:

        JSON with ``authorization_url`` (frontend redirects to it) and the

        CSRF ``state`` token.


        Raises:

        HTTPException(401): no session cookie on the request (``SessionUser``

        is browser-session only, so this is a contradiction).

        AuthenticationError(401): the passkey challenge is unknown, expired,

        already used or issued for another purpose, or the assertion is

        invalid.

        AuthorizationError(403): no fresh proof (wrong or missing password,

        no passkey, no recent verified sign-in).

        RateLimitError(429): too many password proofs.

        HTTPException(500): auth managers not initialised, OAuth2 manager

        missing, or a required env var (GOOGLE_REDIRECT_URI /

        GITHUB_CLIENT_ID) is missing.'
      operationId: link_provider_api_v1_me_account_link_provider_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/LinkProviderRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkProviderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/account/unlink-provider:
    post:
      tags:
      - account-linking
      summary: Unlink Provider
      description: 'Detach a sign-in provider (a linked OAuth identity) from the current account.


        Returns ``{"status": "ok"}`` on success. The service guards the

        invariants and raises, which the global ``memory_cloud_exception_handler``

        maps to HTTP:


        - 404 (NotFoundException): the provider is not linked to this account.

        - 409 (ConflictError): removing it would leave zero sign-in methods.


        On success the owner is emailed a security notice (Issue #1752).'
      operationId: unlink_provider_api_v1_me_account_unlink_provider_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/UnlinkProviderRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnlinkProviderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/account/providers:
    get:
      tags:
      - account-linking
      summary: List Providers
      description: List the sign-in providers (OAuth identities) attached to the session user.
      operationId: list_providers_api_v1_me_account_providers_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/ProvidersListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UnlinkProviderRequest:
      properties:
        provider:
          type: string
          enum:
          - google
          - github
          title: Provider
      type: object
      required:
      - provider
      title: UnlinkProviderRequest
      description: Body for POST /me/account/unlink-provider.
    LinkProviderRequest:
      properties:
        current_password:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Current Password
        assertion:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Assertion
        challenge:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Challenge
        provider:
          type: string
          enum:
          - google
          - github
          title: Provider
      type: object
      required:
      - provider
      title: LinkProviderRequest
      description: 'Body for POST /me/account/link-provider.


        The fresh proof fields (``current_password``, or ``challenge`` +

        ``assertion`` from ``POST /auth/passkeys/proof/options?linking=<provider>``)

        are those of passkey registration; all may be omitted right after a

        verified sign-in.'
    UnlinkProviderResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: UnlinkProviderResponse
      description: Returned by POST /me/account/unlink-provider on success.
    LinkedProvider:
      properties:
        provider:
          type: string
          title: Provider
        linked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Linked At
        last_used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Used At
      type: object
      required:
      - provider
      title: LinkedProvider
      description: 'One linked OAuth identity, as surfaced to the profile UI.


        ``linked_at`` / ``last_used_at`` are pre-serialized to ISO 8601 strings

        with an explicit ``Z`` suffix via ``to_utc_iso`` (the source columns are

        naive UTC ``TIMESTAMP WITHOUT TIME ZONE``), so JS clients don''t reparse

        them as local time.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LinkProviderResponse:
      properties:
        authorization_url:
          type: string
          title: Authorization Url
        state:
          type: string
          title: State
      type: object
      required:
      - authorization_url
      - state
      title: LinkProviderResponse
      description: 'Frontend redirects ``window.location`` to ``authorization_url``.


        The round trip binds the returned identity to the account; the fresh

        proof of the account itself is taken before it starts.'
    ProvidersListResponse:
      properties:
        providers:
          items:
            $ref: '#/components/schemas/LinkedProvider'
          type: array
          title: Providers
      type: object
      required:
      - providers
      title: ProvidersListResponse
      description: All OAuth providers currently linked to the session user.
    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