Skip to manual
gluon

API and integrations

Approve OAuth clients and handle rate limits

Put a client on the allow-list, sign people in with PKCE and stay within the rate limit.

Integration administrator

Applications reach the generated REST API and the MCP server through an OAuth 2.1 client that an administrator has put on the allow-list. Every token acts for one signed-in person, for one resource, under the Capabilities the client was approved for. Gluon has no service identity for these routes: the client_credentials grant is refused, and every client is a public client using PKCE with no secret.

Approve a client

Approving needs the manage-security permission, which the security officer role carries. The admin console has no screen for the allow-list yet, so you call the API with your own token:

Shell
curl -s https://gluon.example/api/oauth/clients \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "clientId": "demo-agent",
    "kind": "static",
    "name": "Demo renewal agent",
    "redirectUris": ["http://127.0.0.1:8765/callback"],
    "capabilities": ["capability:contract-renewal-desk"],
    "scopes": ["read"],
    "ratePerMinute": 20
  }'
  • kind is static, where you list the redirect URIs, or metadata, where clientId is the https URL of the client's Client ID Metadata Document. Gluon reads that document once, at approval, and takes the name and redirect URIs from it. It must name its own URL as client_id, resolve to public addresses only, answer within 5 seconds without a redirect and stay under 64 KB.
  • capabilities are the Capabilities the client may bind a request to.
  • scopes are read (reads, answers and resources) and execute (actions). The default is read.
  • ratePerMinute defaults to 120.

GET /api/oauth/clients lists the allow-list. Posting the same clientId again replaces its approval, which is how you change scopes or the rate. DELETE /api/oauth/clients/{client_id} revokes the client, and every token it holds fails on its next request. A client belongs to one workspace. Dynamic client registration is switched off: there is no registration endpoint.

Sign a person in

Clients discover the endpoints themselves. /.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-protected-resource/api/v1 name each resource and its authorisation server; /.well-known/oauth-authorization-server lists the endpoints. When your proxy forwards only /api, the same documents answer under /api/.well-known/.

  1. Send the person to GET /api/oauth/authorize with response_type=code, client_id, the exact registered redirect_uri, code_challenge with code_challenge_method=S256, resource (https://gluon.example/api/mcp or https://gluon.example/api/v1), scope and state. The person must already be signed in to Gluon, or they get login_required.
  2. Gluon redirects back with a code, valid for 2 minutes and usable once.
  3. Exchange it at the token endpoint:
Shell
curl -s https://gluon.example/api/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=demo-agent \
  -d code=$CODE \
  -d code_verifier=$VERIFIER \
  -d redirect_uri=http://127.0.0.1:8765/callback \
  -d resource=https://gluon.example/api/v1

The access token lives 10 minutes. The refresh token lives 12 hours and rotates on every use; presenting a used refresh token or code again revokes every token from that sign-in. A token for /api/v1 is refused on /api/mcp and the other way round, so a client that uses both signs in once per resource.

Consent is the administrator's approval plus the person's own sign-in, and there is no per-person consent screen yet. The first sign-in records an MCP grant for that person and client, listed with their sessions under People. Suspending the person or revoking the grant ends its tokens for good; signing in again creates a new grant. POST /api/oauth/revoke with either token ends both tokens from that sign-in.

When a request is refused

  • 401 with WWW-Authenticate: Bearer resource_metadata="...": the token is missing, expired, revoked or meant for the other resource. Refresh it, or sign the person in again.
  • 403 insufficient-scope: the token lacks read or execute. Scopes are narrowed to the client's current approval on every request.
  • 429 with Retry-After: the client passed its rate limit.

Rate limits

The limit is a fixed one-minute window per client and person, counted in the database so every replica shares it. Every request counts, failed ones included. Past the limit you get 429 with Retry-After, the seconds left in the window; wait that long before the next request.

The first refusal in each window writes one api.rate-limited audit event. Usage in the admin console lists these under Rate limited clients with the client, channel and limit. A client is an application, so those rows never name the person.

Terminal showing the demo-agent client entry with its redirect URI, Capability, scopes and ratePerMinute.
An approved client on the allow-list: redirect URI, one Capability, read scope and 20 a minute.
Terminal showing a row of 200 codes, then 429 codes, then a retry-after header with the seconds to wait.
A burst past the client's limit turns into 429 answers with a Retry-After header.