DIAL MCP Gateway endpoints and sign-in flow
This reference describes what DIAL MCP Gateway serves, the calls it makes to DIAL Core during a sign-in, the tokens it issues, and its audit events. It is for platform engineers who operate the gateway or diagnose a client's sign-in, and assumes the configuration is in place.
Public paths
The front router publishes one origin and splits it between the gateway and DIAL Core:
| Path on the public origin | Served by |
|---|---|
/healthz | Gateway |
/.well-known/oauth-authorization-server, /.well-known/openid-configuration, and both with a path suffix | Gateway |
/.well-known/oauth-protected-resource/dial/<PATH>/mcp and /.well-known/oauth-protected-resource/apps/<PATH>/mcp | Gateway |
/.well-known/oauth-protected-resource/v1/toolset/<ID>/mcp and .../v1/deployments/<ID>/mcp | DIAL Core |
Any other /.well-known/... path | The router answers 404 with {"detail":"Not Found"} |
/dial/authorize, /dial/token, /dial/revoke, /dial/register, /dial/consent, /dial/callback/..., /dial/jwks.json | Gateway |
/dial/<PATH>/mcp | DIAL Core, as /v1/toolset/<PATH>/mcp |
/apps/<PATH>/mcp | DIAL Core, as /v1/deployments/<PATH>/mcp |
| Everything else | DIAL Core, unchanged |
On both MCP paths, the router drops Core's WWW-Authenticate header from a 401 and sends its own. The header quotes the protected-resource document of the exact path the client called. The router forwards MCP requests byte for byte, keeps the query string, and doesn't buffer responses. A /dial/ or /apps/ path that doesn't end in /mcp gets 404. Sources: routing reference and router maps.
Gateway endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /healthz | Liveness: {"status": "ok"} |
GET | /.well-known/oauth-authorization-server | Authorization server metadata. The same document answers at /.well-known/openid-configuration and at both paths with a suffix. |
GET | /.well-known/oauth-protected-resource/dial/<PATH>/mcp | Protected-resource metadata of a toolset |
GET | /.well-known/oauth-protected-resource/apps/<PATH>/mcp | Protected-resource metadata of an application |
GET | /dial/jwks.json | The public signing keys, active and retained. Core fetches it. |
GET | /dial/authorize | Starts a sign-in |
GET | /dial/callback/idp | Return from the identity provider |
POST | /dial/consent | The user's approve or deny on the approval page |
GET | /dial/callback/upstream | Return from the toolset's authorization server |
POST | /dial/token | Authorization code and refresh token grants |
POST | /dial/revoke | Refresh token revocation |
POST | /dial/register | Dynamic client registration, only when DCR_ENABLED=true |
Sources: discovery and registration routes, authorize, callbacks and consent, and token and revoke. The gateway serves no CORS headers and no interactive API docs, because its clients are local programs, not browser pages.
Discovery documents
The authorization server metadata is one document for every resource. Its issuer is GATEWAY_PUBLIC_ORIGIN at every path where it answers.
| Member | Value |
|---|---|
authorization_endpoint, token_endpoint, jwks_uri, revocation_endpoint | The gateway's /dial/... endpoints |
registration_endpoint | /dial/register, only when DCR_ENABLED=true |
grant_types_supported | authorization_code, refresh_token |
response_types_supported | code |
code_challenge_methods_supported | S256 |
token_endpoint_auth_methods_supported | none; every client is public and uses PKCE |
client_id_metadata_document_supported | true |
authorization_response_iss_parameter_supported | true |
The document lists no scopes and no OpenID Provider members, because the gateway is not an OpenID Provider. Source: discovery.py.
A protected-resource document names its resource, the gateway as the only authorization server, and scopes_supported. The resource is <GATEWAY_PUBLIC_ORIGIN>/dial/<PATH>/mcp for a toolset and <GATEWAY_PUBLIC_ORIGIN>/apps/<PATH>/mcp for an application. Scopes come from a toolset's TOOLSETS entry and are always empty for an application. The gateway serves the document for every valid path without asking Core, so it doesn't reveal which toolsets exist.
Sign-in flow
- Authorization request. The client calls
/dial/authorizewithclient_id,redirect_uri,response_type=code, anS256code_challenge,state, andresource.resourceis required and must be a valid toolset or application URL on the gateway's origin; anything else getsinvalid_target.scopeis accepted and ignored. - Identity provider. The gateway redirects the browser to the identity provider with its own client, scopes, and PKCE challenge. On return, it exchanges the code, verifies the token against the provider's keys, and keeps the provider's refresh token for later refreshes.
- Access check in Core. The gateway reads the resource as the user, with the provider's token. Core's answer decides the next step.
- Approval. On the first sign-in of a client for a user, the gateway shows an approval page with the client's name and ID, the resource, and the redirect URI. Approvals live in memory per user and client.
- Upstream consent. Only for an
OAUTHtoolset with no stored credential. The gateway shows a short page that names the client and the toolset, then sends the browser to the toolset's authorization server. The request uses Core's client ID and code challenge, and the gateway's callback,<GATEWAY_PUBLIC_ORIGIN>/dial/callback/upstream. - Credential sign-in in Core. The gateway passes the returned code to Core, which exchanges it with its own PKCE verifier and stores the credential for the user.
- Code and token. The gateway redirects to the client's
redirect_uriwith a code andiss. The client redeems the code at/dial/tokenwith itscode_verifierand the sameresource.
Every Core call carries Authorization: Bearer <IDENTITY_PROVIDER_TOKEN>:
| Call | When | Core's answer |
|---|---|---|
GET /openai/toolsets/<PATH> | Toolset sign-in | 200 with auth_settings: authentication type, client ID, authorization endpoint, code challenge, scopes, user_level_auth_status, and global_auth_status. 403 no access, 404 unknown. |
GET /openai/applications/<PATH> | Application sign-in | 200, 403 no access, or 404 unknown. |
POST /v1/ops/toolset/signin | After upstream consent | Body: url (the toolset path), credentialsLevel: USER, authenticationType: OAUTH, code, and redirectUri. |
A 401 from Core means Core didn't accept the identity provider's token, which points to Core's identity provider settings rather than to access rights. Any other failure is shown as a deployment fault. Sources: Core client, sign-in call, and the Core routes the flow reads.
A sign-in page that the browser reaches after the flow expired, was evicted, or was already used says the session expired. The user starts the sign-in again from the client.
Tokens
Both tokens are JWTs signed with RS256 by the active signing key, with iss set to GATEWAY_PUBLIC_ORIGIN.
Access token claims
The access token copies every claim of the identity provider's token except those that describe the provider's token itself. The dropped claims are iss, aud, exp, iat, nbf, jti, typ, azp, nonce, at_hash, c_hash, acr, auth_time, cnf, scope, session_state, and sid. Source: tokens.py.
The gateway then sets its own claims:
| Claim | Value |
|---|---|
<ROLES_CLAIM_NAME> | The roles read from ROLES_SOURCE_PATH, always as an array |
aud | The resource URL and GATEWAY_AUDIENCE_MARKER |
typ | access |
jti, iat, exp | A new ID, the issue time, and the expiry after GATEWAY_ACCESS_TOKEN_TTL_SECONDS |
Source: access token.
Core rules that match on a dropped claim, such as scope or acr, never match a gateway token. Core checks only the audience marker, not the resource URL. A user's token for one toolset or application is therefore also accepted on that user's other MCP paths, within the same user's access. Source: what the aud carries.
Refresh tokens and revocation
The refresh token carries sub, aud with the resource URL only, typ: refresh, client_id, resource, and the identity provider's refresh token, encrypted with the custody key. It has no audience marker, so Core never accepts it as an access token. Source: refresh token.
- Refresh. The client sends
grant_type=refresh_tokenwith the sameresource. The gateway gets fresh claims from the identity provider, never contacts the toolset's authorization server, and fails the refresh if the claims can't be read. - Rotation. Each refresh returns a new refresh token with the original expiry. The previous one works for
GATEWAY_ROTATION_GRACE_SECONDSmore. - Code replay. A second use of an authorization code revokes the refresh token that its first use issued.
- Revocation.
POST /dial/revokewithtokenreturns an empty200for any token, valid or not. A refresh token stays revoked until it expires; access tokens can't be revoked.
Revocations are held in memory, like flows and approvals; the registration store is the only state that survives a restart. Source: the pod's single-replica assumption.
Audit events
The gateway writes one JSON line per event to standard output, through the gateway.audit logger. Records of a sign-in carry its flow ID, the client ID, the resource, and, once known, the user's sub. They never carry a token, code, key, verifier, or password.
| Event | When |
|---|---|
flow_refused | A request was refused before a sign-in started; the record carries a fixed reason |
flow_allocated | A sign-in started |
attribution_required | The approval page was shown |
attribution_approved, attribution_refused | The user approved or denied the client |
upstream_callback | The toolset's authorization server returned to the gateway |
signin_result | Core's credential sign-in finished: accepted, access_refused, or failed |
flow_branch_refused | The flow stopped at the access check, for example unknown_toolset or non_oauth_toolset |
flow_leg_failed | A call to the identity provider or Core failed |
credential_free_short_circuit | An application sign-in skipped the credential steps |
code_issued | The client received an authorization code |
token_issued, token_refreshed, token_revoked | Token endpoint and revocation results |
client_registered | A client registered through /dial/register |
Refresh failures carry idp_session_ended, claims_read_failed, or custody_decrypt_failed, which separate an ended session, a provider fault, and a custody key problem. Sources: audit.py and the flow's audit trail.
Further reading
- Environment variables — token lifetimes, rotation, and client registration settings
- Toolsets — authentication types and the credential sign-in API in Core
- Identity providers — how Core verifies tokens and picks a provider
- Coding agents and harnesses — how DIAL governs Claude Code, Codex, and other agents