Kagura AI Account Erasure API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Account Erasure API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: account-erasure
  description: 'GDPR Art.17 / APPI 第22条 right-to-erasure self-service flow (Issue #360). Session-only auth (no API keys).'
paths:
  /api/v1/me/account/erasure-request:
    post:
      tags:
      - account-erasure
      summary: Create Erasure Request
      description: 'Create a pending erasure request and issue a one-time token.


        Returns 201 with the new request''s state. The ``confirm_token`` field

        in the response is populated for password-auth users and ``null`` for

        OAuth users (Issue #469): OAuth users receive the token via email

        instead, keeping the raw secret out of the response surface.


        Other status codes:

        - 403: user is the protected initial admin

        - 409: an active erasure request already exists for this user

        (``ERASURE-006``), or the user owns a workspace with a running

        paid subscription (``BILLING-005``, Issue #1940)

        - 503: OAuth user but the confirmation email failed to dispatch

        (mapped from EmailDispatchError); the pending row is rolled back

        so the user can retry once the email backend recovers.


        The receipt notification (separate from the OAuth confirmation email)

        is dispatched post-commit and is fire-and-forget — it tells the user

        the request was received and is meant to be obvious to the human even

        if they don''t click any confirm link.'
      operationId: create_erasure_request_api_v1_me_account_erasure_request_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErasureRequestCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - account-erasure
      summary: Cancel Erasure Request
      description: 'Cancel the user''s own pending or cooling_off request before it executes.


        Returns 404 if there is no request the user can cancel: none is active,

        or the active one is an admin force-erase (it can be ``cooling_off`` while

        it waits for a vector-store retry, #2282). Returns 409 ``ERASURE-006`` if

        the request started running between the read and the cancel (the sweep

        claimed it), with the status it has now. A cancel that loses to a

        concurrent cancel of the same request (a double-click) answers 200 with

        the cancelled request, like the first one (#2306).'
      operationId: cancel_erasure_request_api_v1_me_account_erasure_request_delete
      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/ErasureRequestStateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - account-erasure
      summary: Get Active Erasure Request
      description: 'Return the user''s active erasure request, or null if none.


        "Active" = pending OR cooling_off OR in_progress. Terminal states

        (complete / failed / cancelled) are not surfaced here — that''s an

        admin-side audit concern, not user-facing UX.'
      operationId: get_active_erasure_request_api_v1_me_account_erasure_request_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:
                anyOf:
                - $ref: '#/components/schemas/ErasureRequestStateResponse'
                - type: 'null'
                title: Response Get Active Erasure Request Api V1 Me Account Erasure Request Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/account/erasure-confirm:
    post:
      tags:
      - account-erasure
      summary: Confirm Erasure Request
      description: 'Confirm a pending request and start the 7-day cooling-off period.


        Password-auth users must re-supply their password as a second factor.

        OAuth users rely on the email-link click + active session cookie.

        Returns 400 on invalid/expired token, 403 on password mismatch, 409

        ``BILLING-005`` when the user owns a workspace with a running paid

        subscription (Issue #1940).'
      operationId: confirm_erasure_request_api_v1_me_account_erasure_confirm_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/ErasureConfirmRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErasureRequestStateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/account/link-provider:
    post:
      tags:
      - account-erasure
      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-erasure
      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-erasure
      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'
  /api/v1/me/account/identity-links:
    get:
      tags:
      - account-erasure
      summary: List Identity Links
      description: 'List the identity links of the session user, and the linkable accounts.


        Identity-linked accounts (separate accounts, not sign-in providers) own

        the same private contexts and the memories in them (roles and workspace

        membership stay per account). Linkable accounts are the other accounts

        signed in on this browser session.'
      operationId: list_identity_links_api_v1_me_account_identity_links_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/IdentityLinksResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - account-erasure
      summary: Link Identity
      description: 'Create an identity link: count another account as the same owner as

        the session user. (A sign-in provider is attached with ``link-provider``.)


        The proof is this browser session: the target must be one of the accounts

        signed in on it, which each entered through its own sign-in, and both the

        session user and the target must have proved their credential here within

        ``IDENTITY_LINK_SIGN_IN_WINDOW`` (#1803, #1818) — a link is symmetric, so a stale

        sign-in on either side would let whoever holds an old session hand that

        account''s private contexts to another. Nothing is ever linked by an email

        match (#481). An id that is not in the session answers 404 whether or not

        such an account exists; freshness is checked only after that.


        Either account may already be in a link set; the sets then merge, and

        every account of both is audited and sent the ``ACCOUNT_LINKED`` notice

        (#1875), not only the two named here.


        Raises (via the global handler): 422 for the caller''s own id, 404 for an

        account not signed in here, 403 (``AUTH-305``) when either account has not

        signed in within the window, 409 when the set would exceed its size cap.'
      operationId: link_identity_api_v1_me_account_identity_links_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/IdentityLinkTarget'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityLinkStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/account/identity-links/unlink:
    post:
      tags:
      - account-erasure
      summary: Unlink Identity
      description: 'Remove an identity link: stop counting another account as the same

        owner as the session user.


        Either side can cut the link from its own session; the other account

        does not have to be signed in. 404 when the account is not linked.'
      operationId: unlink_identity_api_v1_me_account_identity_links_unlink_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/IdentityLinkTarget'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityLinkStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/account/identity-links/leave:
    post:
      tags:
      - account-erasure
      summary: Leave Identity Links
      description: 'Leave the identity-link set: take the session user out of it; the other

        accounts stay linked to each other (#1807).


        ``unlink`` names one account to take out of the caller''s set; ``leave``

        takes the caller out. Every account of the former set is notified.

        404 when the session user is not linked to any account.'
      operationId: leave_identity_links_api_v1_me_account_identity_links_leave_post
      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/IdentityLinkStatusResponse'
        '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.
    IdentityLinksResponse:
      properties:
        linked:
          items:
            $ref: '#/components/schemas/LinkedIdentityItem'
          type: array
          title: Linked
        linkable:
          items:
            $ref: '#/components/schemas/LinkableIdentityItem'
          type: array
          title: Linkable
        signed_in_recently:
          type: boolean
          title: Signed In Recently
          default: false
        sign_in_window_minutes:
          type: integer
          title: Sign In Window Minutes
          default: 10
        providers:
          items:
            type: string
          type: array
          title: Providers
          default: []
      type: object
      required:
      - linked
      - linkable
      title: IdentityLinksResponse
      description: 'The session user''s link set, and what this session could add to it.


        ``signed_in_recently``: the session user itself proved its credential here

        within the link window (#1818), as for a linkable account.'
    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.'
    ErasureConfirmRequest:
      properties:
        token:
          type: string
          title: Token
        password:
          anyOf:
          - type: string
          - type: 'null'
          title: Password
          description: Required only for users with a password. Others omit.
      type: object
      required:
      - token
      title: ErasureConfirmRequest
      description: Payload for POST /me/account/erasure-confirm.
    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.
    IdentityLinkStatusResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: IdentityLinkStatusResponse
      description: Returned by the link and unlink endpoints on success.
    ErasureRequestStateResponse:
      properties:
        request_id:
          title: Request Id
        status:
          title: Status
        is_self_service:
          title: Is Self Service
        requested_at:
          title: Requested At
        confirmed_at:
          title: Confirmed At
        scheduled_for:
          title: Scheduled For
        started_at:
          title: Started At
        completed_at:
          title: Completed At
        cancelled_at:
          title: Cancelled At
        failure_reason:
          title: Failure Reason
      type: object
      required:
      - request_id
      - status
      - is_self_service
      - requested_at
      title: ErasureRequestStateResponse
      description: Read-only view of an erasure request's lifecycle state.
    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
    IdentityLinkTarget:
      properties:
        user_id:
          type: string
          maxLength: 255
          minLength: 1
          title: User Id
      type: object
      required:
      - user_id
      title: IdentityLinkTarget
      description: Body for linking or unlinking an account.
    LinkableIdentityItem:
      properties:
        user_id:
          type: string
          title: User Id
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        signed_in_recently:
          type: boolean
          title: Signed In Recently
          default: false
        providers:
          items:
            type: string
          type: array
          title: Providers
          default: []
      type: object
      required:
      - user_id
      title: LinkableIdentityItem
      description: 'An account signed in on this browser session that is not linked yet.


        ``signed_in_recently``: it proved its credential here within the link

        window (#1818: a password sign-in, or a Google sign-in with a recent

        ``auth_time``), so it can be linked now. An OAuth sign-in alone does not

        count unless the operator allows it.'
    ErasureRequestCreateResponse:
      properties:
        request_id:
          title: Request Id
        status:
          title: Status
        requested_at:
          title: Requested At
        confirm_token:
          title: Confirm Token
          description: One-time confirmation token, valid for 1 hour. **Populated only for users with a password** — they re-enter their password alongside this token at POST /me/account/erasure-confirm. **For users without a password this is null** and the token is delivered via email.
      type: object
      required:
      - request_id
      - status
      - requested_at
      title: ErasureRequestCreateResponse
      description: "Returned after creating a self-service erasure request.\n\nThe confirmation token is delivered through one of two channels\ndepending on whether the account has a password (Issue #469; since #1678\nan OAuth account that added a password counts as a password user):\n\n- **Users with a password**: ``confirm_token`` is populated in this\n  response. The user re-enters their password alongside this token at\n  ``POST /me/account/erasure-confirm`` (the password is the second\n  factor — the response token is the first).\n- **Users without a password**: ``confirm_token`` is ``None`` here. The token is\n  delivered via email to the user's account address as a one-time\n  confirm link. Email is the canonical second factor for OAuth, just\n  as the password re-prompt is for password-auth users — keeping the\n  raw token out of the response body removes a redundant copy that\n  would otherwise widen the disclosure surface (proxy access logs,\n  browser devtools, frontend error-reporters) once email actually\n  delivers it.\n\nThe raw token is stored in Redis under ``erasure_token:{token}`` with\na 1-hour TTL and is single-use regardless of delivery channel. The\nRedis key maps token → ``request_id`` only — it is NOT session-bound.\nConfirmation additionally requires the authenticated session user to\nmatch the erasure request's ``user_id`` (enforced by\n``confirm_self_service``), so a leaked token alone is insufficient\nwithout the matching session cookie.\n\nThe frontend SHOULD treat this token as sensitive and not log it."
    LinkedIdentityItem:
      properties:
        user_id:
          type: string
          title: User Id
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        linked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Linked At
      type: object
      required:
      - user_id
      title: LinkedIdentityItem
      description: 'An account counted as the same owner as the session user.


        ``linked_at`` is an ISO 8601 string with an explicit ``Z`` (``to_utc_iso``).'