> ## 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

> Authenticate to your Link instance with a bearer JWT, and scope each token to the operations it needs.

Every Link API request — admin and runtime — must carry a bearer **JSON Web Token (JWT)** in the
`Authorization` header:

```http theme={null}
Authorization: Bearer <access_token>
```

## Obtaining a token

Link runs on Hellgate-managed infrastructure and authenticates with the platform OAuth2 flow. Exchange your
client credentials for an access token, then send it as a bearer token. Your instance's audience is its instance
name — the `{instance}` slug from your base URL — and you request it together with the scopes your client needs:

```
audience=my-link-instance
```

When Link is invoked transitively by another service — for example [Specter](/products/specter/overview)
composing with Link — the token must name **every** instance in the composition and carry the union of their
scopes (for example, `audience=my-specter-instance my-link-instance`). See
[Composition](/platform/authentication#composition) for details.

See [Platform Authentication](/platform/authentication) for the token endpoint, audiences, and the
client-credentials request.

## Scopes

Each endpoint requires a specific scope. Issue every token with the **least privilege** it needs — runtime
clients should hold only `invoke:execute`, while configuration and operations belong to separate admin clients.

| Scope                          | Grants                                                        |
| ------------------------------ | ------------------------------------------------------------- |
| `invoke:execute`               | Invoke protocol actions (`/api/invoke/{protocol}/{action}`)   |
| `admin:protocols:read`         | Read protocols, requirements, and generated specs             |
| `admin:protocols:write`        | Create, import, and delete protocols                          |
| `admin:backends:read`          | Read backends                                                 |
| `admin:backends:write`         | Create, update, delete, and rotate credentials on backends    |
| `admin:managed-backends:write` | Manage Hellgate-operated (managed) backends and their secrets |
| `admin:keys:read`              | Read message-level-encryption keys                            |
| `admin:keys:write`             | Create, update, delete, and rotate encryption keys            |
| `admin:executions:read`        | Read execution audit logs                                     |

<Note>
  Runtime and admin scopes serve different audiences. Grant `invoke:execute` to your payment or decisioning
  integration; reserve the `admin:*` scopes for operator and back-office clients that configure protocols,
  backends, and keys.
</Note>

## Next steps

<Card title="Quickstart" icon="rocket" href="/products/link/quickstart">
  Use your token to import a protocol, register a backend, and invoke an action.
</Card>