Kagura AI Me OAUTH API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Me OAUTH API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: me-oauth
  description: Refresh the current user's OAuth-backed session credentials
paths:
  /api/v1/me/refresh-oauth:
    post:
      tags:
      - me-oauth
      summary: Refresh Oauth
      description: 'Initiate a manual IdP refresh for the current user.


        Returns:

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

        the CSRF ``state`` token (for symmetry with ``/auth/{provider}/login``).


        Raises:

        HTTPException(400): user is password-auth, or has no usable

        ``auth_provider`` (a legacy null from before #361, or the last

        provider was unlinked). The pointer is set again only by a

        sign-in through the identity the account was created with, once

        its link is established (#1875, ``auth.roles``) — never by

        linking a provider, nor by signing in through one attached

        later, however old its link.

        HTTPException(429): more than 1 request in the current minute

        window. ``Retry-After`` header is set on the response.

        HTTPException(500): OAuth managers not initialised, or required

        environment variables missing.'
      operationId: refresh_oauth_api_v1_me_refresh_oauth_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/RefreshOAuthRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshOAuthResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/oauth/grants:
    get:
      tags:
      - me-oauth
      summary: List Oauth Grants
      description: List the OAuth apps the caller has authorized, newest issuance first.
      operationId: list_oauth_grants_api_v1_me_oauth_grants_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/OAuthGrantResponse'
                title: Response List Oauth Grants Api V1 Me Oauth Grants Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/oauth/grants/{client_id}/default-context:
    put:
      tags:
      - me-oauth
      summary: Set Oauth Grant Default Context
      description: 'Set (or, with ``null``, clear) the MCP default context of one grant.


        The context must be readable by the caller now (viewer); otherwise 404

        ``Context not found``.


        Raises:

        NotFoundException: The caller has no grant for ``client_id``, or

        cannot read the context (404).'
      operationId: set_oauth_grant_default_context_api_v1_me_oauth_grants__client_id__default_context_put
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          title: Client 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/OAuthGrantDefaultContextUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthGrantResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - me-oauth
      summary: Clear Oauth Grant Default Context
      description: 'Clear the MCP default context of one grant.


        Raises:

        NotFoundException: The caller has no grant for ``client_id`` (404).'
      operationId: clear_oauth_grant_default_context_api_v1_me_oauth_grants__client_id__default_context_delete
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          title: Client Id
      - 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'
components:
  schemas:
    RefreshOAuthResponse:
      properties:
        authorization_url:
          type: string
          title: Authorization Url
        state:
          type: string
          title: State
      type: object
      required:
      - authorization_url
      - state
      title: RefreshOAuthResponse
      description: Frontend redirects ``window.location`` to ``authorization_url``.
    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
    OAuthGrantDefaultContextUpdate:
      properties:
        default_context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Default Context Id
          description: The grant's MCP default context; null clears it
      type: object
      required:
      - default_context_id
      title: OAuthGrantDefaultContextUpdate
      description: Body of ``PUT /me/oauth/grants/{client_id}/default-context``.
    OAuthGrantResponse:
      properties:
        client_id:
          title: Client Id
          description: The OAuth client's id
        client_name:
          title: Client Name
          description: The client's registered name
        scopes:
          title: Scopes
          description: Scopes of the caller's live tokens for this client
        default_context_id:
          title: Default Context Id
          description: The grant's MCP default context; null when none
        default_context_name:
          title: Default Context Name
          description: Name of the default context; null when none is set or the caller can no longer read it
        last_issued_at:
          title: Last Issued At
          description: When the newest live token was issued; null when none is live
      type: object
      required:
      - client_id
      - client_name
      title: OAuthGrantResponse
      description: One OAuth app the caller has authorized.
    RefreshOAuthRequest:
      properties:
        return_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Return To
      type: object
      title: RefreshOAuthRequest
      description: 'Optional ``return_to`` lets the frontend control the post-callback

        landing page. Must be a same-origin relative path starting with ``/``;

        absolute or protocol-relative URLs are rejected at the endpoint to

        block open-redirect after successful re-auth. Defaults to

        ``/profile?refreshed=1`` so a vanilla button click works without

        extra wiring.'