Kagura AI Admin Signup Gate API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Admin Signup Gate API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: admin-signup-gate
  description: 'Admin: signup-gate configuration and allowlist management'
paths:
  /api/v1/admin/signup-gate/config:
    get:
      tags:
      - admin-signup-gate
      summary: Get Config
      operationId: get_config_api_v1_admin_signup_gate_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupGateConfigResponse'
    put:
      tags:
      - admin-signup-gate
      summary: Update Config
      operationId: update_config_api_v1_admin_signup_gate_config_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupGateConfigUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupGateConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/signup-gate/allowlist:
    get:
      tags:
      - admin-signup-gate
      summary: List Allowlist
      operationId: list_allowlist_api_v1_admin_signup_gate_allowlist_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AllowlistEntryResponse'
                type: array
                title: Response List Allowlist Api V1 Admin Signup Gate Allowlist Get
    post:
      tags:
      - admin-signup-gate
      summary: Add To Allowlist
      description: 'Add a GitHub or Google user to the manual allowlist (#655).


        Provider is set explicitly via ``payload.provider`` (defaulting to

        ``"github"`` for pre-#655 callers). The required field per provider:


        * ``provider="github"`` → ``github_username`` (resolved to numeric ID

        via the GitHub API).

        * ``provider="google"`` → ``email`` (resolved to OIDC ``sub`` via the

        local ``users`` table; the user must have OAuth''d at least once).'
      operationId: add_to_allowlist_api_v1_admin_signup_gate_allowlist_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllowlistAddRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowlistEntryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/signup-gate/allowlist/{entry_id}:
    delete:
      tags:
      - admin-signup-gate
      summary: Remove From Allowlist
      operationId: remove_from_allowlist_api_v1_admin_signup_gate_allowlist__entry_id__delete
      parameters:
      - name: entry_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Entry Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SignupGateConfigUpdate:
      properties:
        enabled:
          type: boolean
          title: Enabled
        mode:
          type: string
          const: manual
          title: Mode
      type: object
      required:
      - enabled
      - mode
      title: SignupGateConfigUpdate
    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
    AllowlistEntryResponse:
      properties:
        id:
          title: Id
        provider:
          title: Provider
        subject_id:
          title: Subject Id
        subject_label:
          title: Subject Label
        github_user_id:
          title: Github User Id
        github_username:
          title: Github Username
        source:
          title: Source
        state:
          title: State
        added_by_user_id:
          title: Added By User Id
        created_at:
          title: Created At
      type: object
      required:
      - id
      - provider
      - subject_id
      - subject_label
      - github_user_id
      - github_username
      - source
      - state
      - added_by_user_id
      - created_at
      title: AllowlistEntryResponse
      description: 'Allowlist entry read-model.


        #655 added ``provider`` / ``subject_id`` / ``subject_label`` as the

        canonical fields. The legacy ``github_user_id`` / ``github_username``

        fields are retained on the response for backward compatibility with

        pre-#655 admin tooling — for ``provider=''google''`` rows these carry

        the sentinel values written by ``add_to_allowlist_entry``

        (``"google:<sub>"`` / email), which existing GitHub-only consumers

        can ignore via the new ``provider`` field.'
    AllowlistAddRequest:
      properties:
        provider:
          type: string
          enum:
          - github
          - google
          title: Provider
          default: github
        github_username:
          anyOf:
          - type: string
            maxLength: 39
            minLength: 1
            pattern: ^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$
          - type: 'null'
          title: Github Username
        email:
          anyOf:
          - type: string
            maxLength: 247
            pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
          - type: 'null'
          title: Email
      type: object
      title: AllowlistAddRequest
      description: "Allowlist add payload (provider-aware since #655).\n\nThree accepted shapes:\n\n* GitHub legacy (pre-#655): ``{github_username}`` — preserved verbatim\n  so existing admin tooling keeps working without a flag day.\n* GitHub canonical: ``{provider: \"github\", github_username}`` — same\n  semantics, but with the discriminator explicit.\n* Google: ``{provider: \"google\", email}`` — resolves the user's\n  OIDC ``sub`` by looking up an existing ``users`` row with\n  ``auth_provider='google'`` and matching email (v1 bootstrap UX —\n  pre-OAuth invitation lands in Phase 2).\n\nPydantic validates ``github_username`` shape when present (1–39 chars,\nalphanumeric + hyphens, no leading/trailing hyphen) so malformed\npayloads don't spend a GitHub API request (rate-limited to 60/hr\nunauthenticated). The ``email`` field uses the same regex pattern\nthat the rest of the codebase uses for email-string validation\n(see ``models/schemas.py:830``); switching to ``pydantic.EmailStr``\nwould require pulling in ``email-validator`` as a new dependency,\nwhich is not warranted for a single field."
    SignupGateConfigResponse:
      properties:
        enabled:
          type: boolean
          title: Enabled
        mode:
          type: string
          enum:
          - manual
          - github_sponsors
          - both
          title: Mode
        github_sponsors_grace_period_days:
          type: integer
          title: Github Sponsors Grace Period Days
      type: object
      required:
      - enabled
      - mode
      - github_sponsors_grace_period_days
      title: SignupGateConfigResponse
      description: 'Config read-model.


        ``github_sponsors_grace_period_days`` is exposed for Phase 2 UX affordance

        even though Phase 1 doesn''t act on it; showing the value keeps the

        admin UI honest about what will happen once Sponsors mode activates.'