Kagura AI Identity Links API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Identity Links API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: identity-links
  description: 'Identity links (Issue #1784): count several accounts of one person — each with its own sign-in — as one owner of their private contexts. Roles and workspace membership stay per account. Browser session only.'
paths:
  /api/v1/me/account/identity-links:
    get:
      tags:
      - identity-links
      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:
      - identity-links
      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:
      - identity-links
      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:
      - identity-links
      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:
    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.'
    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
    IdentityLinkStatusResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: IdentityLinkStatusResponse
      description: Returned by the link and unlink endpoints on success.
    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.'
    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``).'