OAuth2 access
OAuth2 access is a platform-level capability shared by every service that supports it. This page covers OAuth2 access tokens only — for API keys and mTLS, see the relevant product’s documentation.Obtain client credentials
Client credentials are issued by Hellgate. Contact Hellgate support to request them. Each credential is scoped to a specific service (its audience) and is provisioned with a defined set of maximum scopes based on your request. A token can never exceed the audience and scopes provisioned on the credential it is issued from.Request a token
Exchange your client credentials for an access token at the OAuth2 token endpoint:Audiences
A token names one or more audiences — the service instances it is allowed to call, carried in the token’saud claim. A service rejects any token whose audience does not name it, so a token issued for one instance
cannot be used against another.
Pass audiences in the audience request-body parameter as a space-delimited list. There is no default
audience: the parameter is required on every token request, and each value must be within the audiences
provisioned on your credential. A request without a valid audience is rejected. To target more than one service
with a single token, list each audience (see Composition).
Scopes
You must request scopes through thescope parameter on every token request, as a space-delimited list.
The requested scopes must be a subset of the maximum scopes provisioned on your credential — there are no
default scopes. The available scopes depend on the service; see, for example,
Specter scopes.
Composition
When a token is used transitively across composed services — for example, Specter composing with Link — it must name every service in the composition and carry the scopes each one requires. List all the audiences — each the instance name of a service — together with the union of their scopes when you obtain the token (for example,audience=my-specter-instance my-link-instance).
Use the token
Send the access token in theAuthorization header on every API request:
expires_in is 1800). Cache and reuse it until shortly before it expires, then request a new token
on expiry or on a 401 response.