Skip to main content
Hellgate® Cloud Platform services authenticate with one of three mechanisms — API keys, OAuth2 access tokens (bearer JWTs), or mTLS. All three are supported today. OAuth2 access tokens complement the API keys used by Guardian and Commerce and, over time, will become the standard mechanism across the platform.
ProductAPI keyOAuth2mTLS
Specter—✓—
Guardian✓——
Commerce v1✓—✓
Commerce v2✓——

​
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: 
https://auth.eu1.hellgate.cloud/oauth2/token
You authenticate to this endpoint with HTTP Basic authentication, sending your client ID and client secret. See the Authentication API reference for the full request and response.

​
Audiences

A token names one or more audiences — the service instances it is allowed to call, carried in the token’s aud 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 the scope parameter on every token request. 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 (for example, audience=specter link) together with the union of their scopes when you obtain the token.

​
Use the token

Send the access token in the Authorization header on every API request: 
Authorization: Bearer <access_token>
The token carries the scopes that gate access to individual endpoints and expires 30 minutes after it is issued (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.