> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Hellgate Cloud Platform services authenticate with API keys, OAuth2 bearer tokens, or mTLS. This page covers OAuth2 access tokens.

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.

| Product                                       | API key | OAuth2 | mTLS |
| --------------------------------------------- | ------- | ------ | ---- |
| [Specter](/products/specter/overview)         | —       | ✓      | —    |
| [Guardian](/products/guardian/overview)       | ✓       | —      | —    |
| [Commerce v1](/products/commerce/v1/overview) | ✓       | —      | ✓    |
| [Commerce v2](/products/commerce/v2/overview) | ✓       | —      | —    |

## 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](/platform/api-reference/overview) 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](#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](/products/specter/authentication#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 the `Authorization` header on every API request:

```http theme={null}
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.