giljo-ai OAuth API

openapi: 3.2.0
info:
  title: Giljo Agent Message Hub OAuth API
  description: '## Authenticated Agent Message Board REST API


    Giljo Agent Message Hub provides the REST API for authenticated users,

    shared message threads, tasks, WebSocket updates, and MCP connectivity.


    ### Key Features:

    - **Authentication**: Dashboard sessions, API keys, and OAuth 2.1

    - **Message Hub**: Shared threads, participants, baton passing, and messages

    - **Tasks**: Tenant-scoped task tracking

    - **Real-time Updates**: WebSocket support for live message and task updates

    - **MCP Endpoint**: Agent tool connectivity through `/mcp`


    ### Authentication:

    API authentication can be enabled via configuration. Supports API key and OAuth methods.


    ### WebSocket:

    Connect to `/ws/{client_id}` for real-time updates on threads, messages, and tasks.


    ### Rate Limiting:

    Rate limiting can be configured per tenant. Default: 60 requests/minute.'
  contact:
    name: GiljoAI Support
    url: https://giljo.ai/
    email: infoteam@giljo.ai
  license:
    name: Elastic License 2.0
    url: https://giljo.ai/
  version: 1.0.0
servers:
- url: /
  description: This server
tags:
- name: OAuth
  description: OAuth 2.1 authorization server metadata and token endpoints
paths:
  /api/oauth/authorize:
    post:
      tags:
      - OAuth
      summary: Authorize
      description: 'Process OAuth authorization consent and generate an authorization code.


        Requires the user to be authenticated via JWT cookie. Validates the OAuth

        parameters, generates an authorization code bound to the user and PKCE

        challenge, and returns the redirect URI with the code and state.


        Args:

        request: FastAPI request object.

        body: OAuth authorization parameters.

        current_user: Authenticated user from JWT dependency.

        db: Database session.


        Returns:

        JSON with the redirect_uri containing the authorization code and state.


        Raises:

        HTTPException 400: If OAuth parameter validation fails.'
      operationId: authorize_api_oauth_authorize_post
      security:
      - CookieSession: []
      parameters:
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: access_token
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Access Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/oauth/token:
    post:
      tags:
      - OAuth
      summary: Token
      description: 'Exchange an authorization code or refresh token for a JWT access token.


        Public endpoint (no authentication required). Accepts THREE request

        shapes:


        1. ``application/x-www-form-urlencoded`` body — RFC 6749 §3.2 canonical

        (claude.ai uses this).

        2. ``application/json`` body — pragmatic norm matching Google / GitHub /

        Auth0 / Okta. ChatGPT connector uses this (live evidence on demo

        2026-05-10 10:06:12 EDT, Azure CIDR 172.212.159.x).

        3. HTTP Basic Auth header (``Authorization: Basic

        ``) for ``client_secret_basic`` clients

        — RFC 6749 §2.3.1. Header credentials take precedence over body

        values when both are supplied.


        The handler logic (validation, PKCE branching, secret verification) is

        identical regardless of input shape; only parsing differs.


        Body fields (form or JSON):

        grant_type: "authorization_code" or "refresh_token".

        code: The authorization code from the authorize step.

        client_id: OAuth client identifier (optional if Basic Auth header

        supplies it).

        redirect_uri: Must match the URI used during authorization.

        code_verifier: PKCE code verifier (RFC 7636). Required for public

        clients (no ``client_secret_hash`` on the resolved record),

        optional for confidential clients that authenticate via

        ``client_secret`` (RFC 6749 §6 treats client authentication and

        PKCE as alternative proof-of-possession mechanisms). When a

        confidential client DOES include a verifier, it must match the

        stored challenge (defense-in-depth).

        resource: RFC 8707 resource indicator. Optional at /token: when

        the auth-code record carries a bound resource, the bound value

        is authoritative — if the client asserts ``resource`` here it

        MUST equal the bound value (mismatch → ``invalid_grant`` 400);

        if the client omits it, the server falls back to the bound

        value per RFC 8707 §2 (SHOULD use the value from /authorize).

        client_secret: Plaintext client secret for confidential clients

        registered via RFC 7591 DCR. Required when the resolved client

        carries a ``client_secret_hash``; rejected as ``invalid_client``

        (401) when missing or wrong. Public PKCE-only clients (built-in

        CE) MUST omit this field — sending it on a public client is also

        ``invalid_request`` (400).


        Returns:

        TokenResponse with access_token, token_type, and expires_in.


        Raises:

        HTTPException 400: ``invalid_request`` (malformed body, missing

        required field), ``unsupported_grant_type``, or ``invalid_grant``

        (unknown / spent / expired code, client / redirect_uri / resource

        mismatch, PKCE failure).

        HTTPException 401: ``invalid_client`` (confidential auth failed).'
      operationId: token_api_oauth_token_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
  /api/oauth/refresh:
    post:
      tags:
      - OAuth
      summary: Refresh
      description: 'Exchange a refresh token for a new access+refresh pair.


        Public (unauthenticated) endpoint. Serves BOTH confidential clients

        (``client_secret_post`` / ``client_secret_basic``) AND public PKCE

        clients. Public clients present no secret — possession of the one-time-use

        rotating refresh token is the proof-of-possession (RFC 8252 / OAuth 2.1

        §4.3.1); the service rotates the token on every call and revokes the whole

        family on reuse of a consumed token.


        Accepts the same three request shapes as /token:

        form-encoded body, JSON body, or HTTP Basic Auth header for the client

        credentials.


        Body fields (form or JSON):

        grant_type: Must be ``"refresh_token"`` (RFC 6749 §6).

        refresh_token: Plaintext refresh token from the prior /token or

        /refresh response.

        client_id: Client identifier (DCR-registered) — optional when

        supplied via Basic Auth header.

        client_secret: Confidential client secret (required + verified) —

        optional when supplied via Basic Auth header.


        Returns:

        TokenResponse with new ``access_token`` + rotated ``refresh_token``.

        The previous refresh token is marked revoked; reuse triggers

        family-wide revocation per RFC 6749 §10.4.


        Raises:

        HTTPException 400: ``invalid_request`` (grant_type wrong, missing field)

        or ``invalid_grant`` (token unknown / revoked / expired).

        HTTPException 401: ``invalid_client`` (auth failed).'
      operationId: refresh_api_oauth_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
  /api/oauth/.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      summary: Oauth Metadata
      description: 'Return OAuth 2.1 authorization server metadata (RFC 8414).


        This is a public endpoint. Returns the server''s OAuth configuration

        so clients can discover endpoints and supported features.


        Args:

        request: FastAPI request object (for building issuer URL).


        Returns:

        OAuthMetadataResponse with server metadata.'
      operationId: oauth_metadata_api_oauth__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthMetadataResponse'
  /api/oauth/revoke:
    post:
      tags:
      - OAuth
      summary: Revoke
      description: 'RFC 7009 OAuth 2.0 Token Revocation.


        Body (form or JSON): ``token`` (required), ``token_type_hint`` (optional;

        ``access_token`` or ``refresh_token``). The hint is advisory -- on first-

        type miss the service tries the other type.


        Response is ALWAYS 200 OK with empty body except when ``token`` is

        absent (400 invalid_request). Unknown, malformed, foreign, or already-

        revoked tokens still return 200 (RFC 7009 §2.2 -- no token-validity leak).


        Side effects:

        - Access JWT: persists a row in ``oauth_revoked_tokens`` keyed by the

        JWT''s ``jti`` claim. The /mcp Bearer middleware rejects revoked

        tokens on the next request.

        - Refresh token: flips ``revoked=true`` on the entire token family

        (RFC 6749 §10.4 / OAuth 2.1 Security BCP).'
      operationId: revoke_api_oauth_revoke_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      summary: Oauth Metadata Root Mirror
      description: 'RFC 8414 root-path mirror of `/api/oauth/.well-known/oauth-authorization-server`.


        Spec-compliant clients (Claude.ai, MCP CLI tooling) probe the root path

        first. Body is identical to the `/api/oauth/...` route — same handler

        invoked for a single source of truth.'
      operationId: oauth_metadata_root_mirror__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthMetadataResponse'
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - OAuth
      summary: Oauth Protected Resource Metadata
      description: 'Return OAuth 2.0 Protected Resource metadata for `/mcp` (RFC 9728).


        Tells clients which authorization server issues tokens for this resource

        and how to present them. The `WWW-Authenticate` header on `/mcp` 401s

        points here so a client that just got rejected can self-bootstrap.'
      operationId: oauth_protected_resource_metadata__well_known_oauth_protected_resource_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectedResourceMetadataResponse'
  /.well-known/mcp-server-info:
    get:
      tags:
      - OAuth
      summary: Mcp Server Info
      description: 'Return MCP spec-version + capability discovery document.


        Public, unauthenticated endpoint. Capability data is read from canonical

        sources — `TOOL_SCOPES` (defined alongside the MCPServer instance) for the

        scope-per-tool map, `giljo_mcp.__version__` for `server_version`. No

        duplicate registries.'
      operationId: mcp_server_info__well_known_mcp_server_info_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerInfoResponse'
components:
  schemas:
    OAuthMetadataResponse:
      properties:
        issuer:
          type: string
          title: Issuer
        authorization_endpoint:
          type: string
          title: Authorization Endpoint
        token_endpoint:
          type: string
          title: Token Endpoint
        response_types_supported:
          items:
            type: string
          type: array
          title: Response Types Supported
        code_challenge_methods_supported:
          items:
            type: string
          type: array
          title: Code Challenge Methods Supported
        grant_types_supported:
          items:
            type: string
          type: array
          title: Grant Types Supported
        scopes_supported:
          items:
            type: string
          type: array
          title: Scopes Supported
          description: OAuth scopes this authorization server grants (RFC 8414 §3.2).
        token_endpoint_auth_methods_supported:
          items:
            type: string
          type: array
          title: Token Endpoint Auth Methods Supported
          description: Client auth methods supported by /token (RFC 8414 §3.2).
        registration_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Registration Endpoint
        revocation_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Revocation Endpoint
        mcp_spec_versions_supported:
          items:
            type: string
          type: array
          title: Mcp Spec Versions Supported
          description: MCP protocol versions implemented by this server.
        authorization_response_iss_parameter_supported:
          type: boolean
          title: Authorization Response Iss Parameter Supported
          default: true
        client_id_metadata_document_supported:
          type: boolean
          title: Client Id Metadata Document Supported
          default: true
      type: object
      required:
      - issuer
      - authorization_endpoint
      - token_endpoint
      - response_types_supported
      - code_challenge_methods_supported
      - grant_types_supported
      title: OAuthMetadataResponse
      description: 'OAuth 2.1 authorization server metadata (RFC 8414).


        All endpoint URLs are absolute (per RFC 8414 §2). The optional

        ``registration_endpoint`` is advertised only when DCR is available

        (SaaS/demo edition); CE omits the field rather than advertising a

        404 path.'
    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
    ProtectedResourceMetadataResponse:
      properties:
        resource:
          type: string
          title: Resource
        authorization_servers:
          items:
            type: string
          type: array
          title: Authorization Servers
        scopes_supported:
          items:
            type: string
          type: array
          title: Scopes Supported
        bearer_methods_supported:
          items:
            type: string
          type: array
          title: Bearer Methods Supported
        resource_indicators_supported:
          type: boolean
          title: Resource Indicators Supported
          default: true
      type: object
      required:
      - resource
      - authorization_servers
      - scopes_supported
      - bearer_methods_supported
      title: ProtectedResourceMetadataResponse
      description: 'OAuth 2.0 Protected Resource metadata (RFC 9728).


        Per RFC 8707 §3, advertises ``resource_indicators_supported: true`` so

        spec-aware clients (claude.ai connector backend) know they MUST send

        ``resource`` to /authorize and /token. The server enforces that

        binding.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AuthorizeRequest:
      properties:
        client_id:
          type: string
          maxLength: 256
          title: Client Id
          description: OAuth client identifier
        redirect_uri:
          type: string
          maxLength: 2048
          title: Redirect Uri
          description: URI to redirect after authorization
        code_challenge:
          type: string
          maxLength: 128
          title: Code Challenge
          description: PKCE S256 code challenge
        code_challenge_method:
          type: string
          maxLength: 16
          title: Code Challenge Method
          description: PKCE challenge method (must be S256)
          default: S256
        scope:
          type: string
          maxLength: 512
          title: Scope
          description: Requested OAuth scope. Must be a subset of ['mcp:agent', 'mcp:read', 'mcp:write']. The orchestration scope (`mcp:agent`) IS grantable here so an OAuth client reaches API-key parity (guarded by the localhost redirect allowlist + consent).
          default: mcp:read mcp:write mcp:agent
        state:
          type: string
          maxLength: 4096
          title: State
          description: Opaque state value for CSRF protection
          default: ''
        response_type:
          type: string
          maxLength: 32
          title: Response Type
          description: OAuth response type (must be code)
          default: code
        consent:
          type: string
          enum:
          - allow
          - deny
          title: Consent
          description: The authenticated user's explicit authorization decision.
          default: allow
        resource:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Resource
          description: RFC 8707 resource indicator. Identifies the target resource server (typically the canonical MCP URI). When supplied, it is persisted onto the auth-code record and re-asserted at /token.
      type: object
      required:
      - client_id
      - redirect_uri
      - code_challenge
      title: AuthorizeRequest
      description: Request body for the OAuth authorize (consent) endpoint.
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
          default: bearer
        expires_in:
          type: integer
          title: Expires In
          default: 86400
        refresh_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh Token
        refresh_expires_in:
          anyOf:
          - type: integer
          - type: 'null'
          title: Refresh Expires In
      type: object
      required:
      - access_token
      title: TokenResponse
      description: Response body for the OAuth token endpoint.
    McpServerInfoResponse:
      properties:
        spec_versions:
          items:
            type: string
          type: array
          title: Spec Versions
        capabilities:
          additionalProperties: true
          type: object
          title: Capabilities
        server_name:
          type: string
          title: Server Name
        server_version:
          type: string
          title: Server Version
      type: object
      required:
      - spec_versions
      - capabilities
      - server_name
      - server_version
      title: McpServerInfoResponse
      description: 'MCP spec-version + capability discovery document.


        Lightweight companion to OAuth AS-metadata: exposes the declared MCP

        spec-version list, the server identity, and a capability snapshot read

        from the canonical MCPServer tool registry. Surface for conformance

        discovery without forcing the client through `initialize`.'
  securitySchemes:
    CookieSession:
      type: apiKey
      in: cookie
      name: access_token
    FirstLoginSession:
      type: apiKey
      in: cookie
      name: access_token