Skip to main content

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 originServed by
/healthzGateway
/.well-known/oauth-authorization-server, /.well-known/openid-configuration, and both with a path suffixGateway
/.well-known/oauth-protected-resource/dial/<PATH>/mcp and /.well-known/oauth-protected-resource/apps/<PATH>/mcpGateway
/.well-known/oauth-protected-resource/v1/toolset/<ID>/mcp and .../v1/deployments/<ID>/mcpDIAL Core
Any other /.well-known/... pathThe router answers 404 with {"detail":"Not Found"}
/dial/authorize, /dial/token, /dial/revoke, /dial/register, /dial/consent, /dial/callback/..., /dial/jwks.jsonGateway
/dial/<PATH>/mcpDIAL Core, as /v1/toolset/<PATH>/mcp
/apps/<PATH>/mcpDIAL Core, as /v1/deployments/<PATH>/mcp
Everything elseDIAL 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​

MethodPathPurpose
GET/healthzLiveness: {"status": "ok"}
GET/.well-known/oauth-authorization-serverAuthorization 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>/mcpProtected-resource metadata of a toolset
GET/.well-known/oauth-protected-resource/apps/<PATH>/mcpProtected-resource metadata of an application
GET/dial/jwks.jsonThe public signing keys, active and retained. Core fetches it.
GET/dial/authorizeStarts a sign-in
GET/dial/callback/idpReturn from the identity provider
POST/dial/consentThe user's approve or deny on the approval page
GET/dial/callback/upstreamReturn from the toolset's authorization server
POST/dial/tokenAuthorization code and refresh token grants
POST/dial/revokeRefresh token revocation
POST/dial/registerDynamic 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.

MemberValue
authorization_endpoint, token_endpoint, jwks_uri, revocation_endpointThe gateway's /dial/... endpoints
registration_endpoint/dial/register, only when DCR_ENABLED=true
grant_types_supportedauthorization_code, refresh_token
response_types_supportedcode
code_challenge_methods_supportedS256
token_endpoint_auth_methods_supportednone; every client is public and uses PKCE
client_id_metadata_document_supportedtrue
authorization_response_iss_parameter_supportedtrue

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​

  1. Authorization request. The client calls /dial/authorize with client_id, redirect_uri, response_type=code, an S256 code_challenge, state, and resource. resource is required and must be a valid toolset or application URL on the gateway's origin; anything else gets invalid_target. scope is accepted and ignored.
  2. 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.
  3. Access check in Core. The gateway reads the resource as the user, with the provider's token. Core's answer decides the next step.
  4. 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.
  5. Upstream consent. Only for an OAUTH toolset 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.
  6. 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.
  7. Code and token. The gateway redirects to the client's redirect_uri with a code and iss. The client redeems the code at /dial/token with its code_verifier and the same resource.

Every Core call carries Authorization: Bearer <IDENTITY_PROVIDER_TOKEN>:

CallWhenCore's answer
GET /openai/toolsets/<PATH>Toolset sign-in200 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-in200, 403 no access, or 404 unknown.
POST /v1/ops/toolset/signinAfter upstream consentBody: 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:

ClaimValue
<ROLES_CLAIM_NAME>The roles read from ROLES_SOURCE_PATH, always as an array
audThe resource URL and GATEWAY_AUDIENCE_MARKER
typaccess
jti, iat, expA 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_token with the same resource. 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_SECONDS more.
  • Code replay. A second use of an authorization code revokes the refresh token that its first use issued.
  • Revocation. POST /dial/revoke with token returns an empty 200 for 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.

EventWhen
flow_refusedA request was refused before a sign-in started; the record carries a fixed reason
flow_allocatedA sign-in started
attribution_requiredThe approval page was shown
attribution_approved, attribution_refusedThe user approved or denied the client
upstream_callbackThe toolset's authorization server returned to the gateway
signin_resultCore's credential sign-in finished: accepted, access_refused, or failed
flow_branch_refusedThe flow stopped at the access check, for example unknown_toolset or non_oauth_toolset
flow_leg_failedA call to the identity provider or Core failed
credential_free_short_circuitAn application sign-in skipped the credential steps
code_issuedThe client received an authorization code
token_issued, token_refreshed, token_revokedToken endpoint and revocation results
client_registeredA 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​