Kagura AI Google Oauth2 API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Google Oauth2 API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: google-oauth2
  description: Google OAuth2 login and callback flow
paths:
  /api/v1/auth/google/login:
    get:
      tags:
      - google-oauth2
      summary: Google Login
      description: 'Initiate Google OAuth2 login flow.


        Generates OAuth2 authorization URL with CSRF state token.


        Args:

        redirect_uri: Optional custom redirect URI (defaults to configured URI)

        return_to: If provided, auto-redirects browser to Google (for iOS/browser users)

        invite: Optional closed-beta invite token (#1581). Its hash is bound to

        this flow''s state for the signup gate; malformed values are ignored.

        accepted_terms: The terms version the person agreed to on the sign-in

        page (#1665). Bound to this flow''s state; ignored while

        ``TERMS_VERSION`` is empty.

        link_proof: This sign-in proves the account for an identity link

        (#1818): Google is asked for ``auth_time``, and the callback

        records it from the verified ID token. Ordinary sign-ins send the

        same request as before.

        locale: The UI language the sign-in page was showing (``en`` / ``ja``,

        #2700). Bound to this flow''s state; a NEW account starts in it,

        an existing one keeps its own. Unsupported values are ignored.

        timezone: The browser''s IANA time zone (e.g. ``Asia/Tokyo``, #2700).

        Same handling as ``locale``.


        Returns:

        If return_to: RedirectResponse to Google OAuth (browser user)

        Otherwise: JSON {authorization_url, state} (API client)


        Example:

        GET /api/v1/auth/google/login (API client)

        Response: {"authorization_url": "...", "state": "..."}


        GET /api/v1/auth/google/login?return_to=... (browser user)

        Response: 303 Redirect to Google OAuth


        Note:

        Frontend should redirect user to authorization_url.

        State token is stored in Redis for CSRF validation.'
      operationId: google_login_api_v1_auth_google_login_get
      parameters:
      - name: redirect_uri
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Uri
      - name: return_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Return To
      - name: add_account
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Add Account
      - name: invite
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Invite
      - name: accepted_terms
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Accepted Terms
      - name: link_proof
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Link Proof
      - name: locale
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
      - name: timezone
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/google/callback:
    get:
      tags:
      - google-oauth2
      summary: Google Callback
      description: 'Handle Google OAuth2 callback.


        Exchanges authorization code for access token, retrieves user info,

        creates session, and sets HttpOnly cookie.


        Args:

        request: FastAPI request (used for IP / User-Agent capture on the

        audit row written by ``RoleManager.ensure_user`` when the IdP-

        provided email differs from the stored value).

        code: OAuth2 authorization code from Google.

        state: CSRF state token (must match stored state).


        Returns:

        Redirect to dashboard with session cookie set. Every failure class on

        this browser-facing route 303-redirects to ``/login`` with a

        well-known ``error`` token (#1381) — raw JSON is never the terminal

        state for an interactive user.


        Example:

        GET /api/v1/auth/google/callback?code=xxx&state=yyy

        → Sets cookie: kagura_session=...

        → Redirects to /dashboard


        Security:

        - State validation (CSRF protection)

        - HttpOnly cookie (XSS protection)

        - Secure cookie (HTTPS only)

        - SameSite=Lax (CSRF protection)'
      operationId: google_callback_api_v1_auth_google_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: OAuth2 authorization code
          title: Code
        description: OAuth2 authorization code
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: CSRF state token
          title: State
        description: CSRF state token
      - name: error
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: OAuth2 error code (e.g. access_denied) when the user cancels
          title: Error
        description: OAuth2 error code (e.g. access_denied) when the user cancels
      - name: error_description
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Human-readable OAuth2 error detail (not reflected)
          title: Error Description
        description: Human-readable OAuth2 error detail (not reflected)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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