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

# Authentication

> Plugin JWTs and access tokens, and what each one can reach.

Entire plugins use two credentials. You sign a **plugin JWT** with your own key to talk to a Core. You exchange it for an **access token** to talk to a repository's region, or to create a repository on a Core.

| Credential | Signed by | Accepted by | Lifetime |
| :- | :- | :- | :- |
| Plugin JWT | Your service, with its Ed25519 key | Two Core endpoints: list repositories, mint access token | At most 5 minutes |
| Access token | Entire, for one installation | The region API, as a bearer token. On a Core, only the create-repository endpoint | About 45 minutes |

Your service never holds customer passwords or long-lived tokens. See [Building a Plugin](https://docs.entire.com/guides/api/plugins/overview.md) for the full flow.

## Plugin JWTs

Sign a fresh JWT for each call, or reuse one for a few minutes:

| Claim | Value |
| :- | :- |
| `iss` | `urn:entire:plugin:{slug}`, with your slug. |
| `aud` | The Core you are calling, followed by `/api/authz/sts`. For example `https://us.auth.entire.io/api/authz/sts`. |
| `plugin_id` | Your slug. |
| `installation_id` | The installation you are acting for. |
| `iat` | Now, minus 30 seconds. Core allows no clock skew on this claim. |
| `exp` | At most 5 minutes after `iat`. Core refuses more than 10 minutes when your keys are registered as PEM. |

Header: `"alg": "EdDSA"`, and `"kid"` when you registered a JWKS URL.

## Access tokens

Mint an access token with the [access-tokens endpoint](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md#mint-an-access-token). What the token can reach depends on what you ask for:

| You request | You get |
| :- | :- |
| A `repository_id` and some permissions | A token for that repository alone, with only those permissions. Prefer this. |
| No repository, and every permission you registered | A token for every selected repository, with every permission, including `repositories:create` if you registered it. Treat it as the whole installation's authority. |
| No repository, and only `{"installations": "read"}` | A token that reaches no repository. |
| No repository, and only `{"repositories": "create"}` | A token that reaches no repository. It can only [create repositories](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md#create-a-repository) in the installation's project. |
| A `repository_id` and `repositories:create` | `400 invalid_request`. Creating is never scoped to a repository. |
| No repository, and any other permissions | `400 repository_required`. |

Hand only a token scoped to one repository to code you trust less than your service, such as a customer's build job.

Cache tokens until shortly before they expire. Entire limits how many tokens one installation can mint, and answers `429 rate_limited` with a `Retry-After` header, in seconds, when you exceed it.

Send credentials only to hosts under `entire.io` that Entire named: a Core, or an `api_base_url` from the repository list. See [Regions and routing](https://docs.entire.com/guides/api/regions-and-routing.md).