giljo-ai OAuth API
OAuth 2.1 authorization server metadata and token endpoints
OAuth 2.1 authorization server metadata and token endpoints
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/giljo-ai:giljo-ai-oauth-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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