Authentication

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

Documentation

Accounts and projects

Git

Trails

Sessions and checkpoints

Webhooks

Authentication

Plugin JWTs

Access tokens

​Plugin JWTs

​Access tokens

Plugin JWTs

Access tokens