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

# Service Accounts

> Give CI jobs, cloud functions, and agents their own access to Entire repositories.

A service account lets a CI job, a cloud function, or an agent work with your repositories without using your login. Each service account belongs to one project, and you give it access with the same roles you give people.

## What a Service Account Can Access

You can grant a service account `reader`, `writer`, or `admin` on one repository, or on every repository in its project. Grant the narrowest role that works. Commands that list a project's repositories, such as `entire repo list`, need a grant on the whole project. A service account can't reach repositories in other projects.

> [!NOTE]
>
> Service accounts work in projects hosted on Entire, not in GitHub mirror projects.

An organization or account can have up to 5 service accounts across all its projects.

## How a Service Account Signs In

A service account signs in with one of two credentials:

* **An OpenID Connect (OIDC) token** from the platform your code runs on, such as GitHub Actions or Cursor. You need to bind the platform to the service account once. Each job or agent then signs in with its own short-lived token, with no secret to store.
* **A service account secret**, on any other platform. You need to create the [secret and store it where your code runs](https://docs.entire.com/guides/configuration/service-accounts.md#sign-in-with-a-secret).

## Before You Start

You need permission to manage the Entire project.

## Set Up a Service Account

> [tab] entire.com
>
> Use entire.com when you want to create a service account and give it access from the web interface.
>
> ### Create a Service Account in entire.com
>
> 1. In your project, open **Settings** and select **Service accounts**.
> 2. Select **Create service account**.
> 3. Enter a name, such as `deploy`, and select **Create**.
>
> ![Service accounts page in a project's settings](https://mintcdn.com/entire/XzhVcSYZJfUTYCxk/images/service-accounts-list.png?fit=max\&auto=format\&n=XzhVcSYZJfUTYCxk\&q=85\&s=d529b932d9151180e78c34163965effb)
>
> The dialog shows the service account's ID and Auth URL. Your jobs use both to sign in.
>
> ![Service account created dialog with the ID and Auth URL](https://mintcdn.com/entire/XzhVcSYZJfUTYCxk/images/service-accounts-created.png?fit=max\&auto=format\&n=XzhVcSYZJfUTYCxk\&q=85\&s=cbddfc98a448af165717a0c3881e53d9)
>
> ### Grant Repository Access
>
> Open the service account. Under **Repository access**, select **Add repository access**. Choose a repository and a role, then select **Add**.
>
> You can only grant access to individual repositories here. To grant access to every repository in the project, use the **CLI** tab.
>
> ![Add repository access dialog with a repository list and a role](https://mintcdn.com/entire/XzhVcSYZJfUTYCxk/images/service-accounts-add-repository-access.png?fit=max\&auto=format\&n=XzhVcSYZJfUTYCxk\&q=85\&s=4b6117a46b4c14a9b6f6e371babf02c9)
>
> ### Add a Binding
>
> A binding lets jobs on another platform, such as GitHub Actions, sign in as the service account. Under **Bindings**, select **Add binding** and choose the **Provider**.
>
> Fill in the required fields. Each field is a pin, a value the job's token must match, such as your repository name. To add more pins, such as a branch, select **Add condition**. Then select **Add**. [OpenID Connect (OIDC)](https://docs.entire.com/guides/configuration/oidc.md#platforms) says where to find each platform's values.
>
> ![Add binding dialog with a provider and its pins](https://mintcdn.com/entire/XzhVcSYZJfUTYCxk/images/service-accounts-add-binding.png?fit=max\&auto=format\&n=XzhVcSYZJfUTYCxk\&q=85\&s=c5a9a32e4705b7026c5eb2cca4579ff4)
>
> For a GitHub Actions binding, the page then shows the workflow step to add. For other platforms, see [OpenID Connect (OIDC)](https://docs.entire.com/guides/configuration/oidc.md) for how a job gets its token and signs in.
>
> ### Create a Secret
>
> Creating secrets in entire.com is coming soon. Until then, [create a secret with the CLI](https://docs.entire.com/guides/configuration/service-accounts.md#sign-in-with-a-secret).
>
> ### Delete a Service Account
>
> Open the service account and select **Delete service account**. Type its name to confirm. Its grants, bindings, and secrets are removed, and jobs that sign in as it stop working.

> [tab] CLI
>
> You can create service accounts, give them access, and bind platforms with the Entire CLI. To create a secret, see [Sign In with a Secret](#sign-in-with-a-secret).
>
> ### Create a Service Account with the CLI
>
> You need permission to manage the Entire project. Create the service account and give it access to one repository:
>
> ```bash theme={null}
> entire service-account create acme deploy
> entire service-account grant acme/deploy --repo web --role reader
> ```
>
> Use `--repo` to grant access to one repository, or `--project` to grant access to every repository in the project.
>
> To see what a service account can access, run `entire service-account grants acme/deploy`. To remove access, run `entire service-account revoke acme/deploy --repo web`. You can shorten `entire service-account` to `entire sa`. See the [`entire service-account` reference](https://docs.entire.com/cli-reference/service-account) for every command.
>
> ### Bind a Platform
>
> If your jobs run on a platform that issues OIDC tokens, such as GitHub Actions, bind it to the service account. Its jobs can then sign in without a secret:
>
> ```bash theme={null}
> entire service-account bind acme/deploy --provider github-actions --pin repository=acme/web
> ```
>
> `entire service-account providers <name>` lists a platform's pins. See [OpenID Connect (OIDC)](https://docs.entire.com/guides/configuration/oidc.md) for each platform's pins and how its jobs sign in.

## Sign In with a Secret

On a platform without OIDC, a service account signs in with a secret, a credential you store where your code runs. Creating secrets in entire.com is coming soon, so create one with the CLI. You need permission to manage the Entire project.

```bash theme={null}
entire service-account secret create acme/deploy > deploy.secret
```

The command prints the secret once, so redirect it into a file or your secret store. A secret starts with `ent_svc_` and ends with a checksum that lets a client catch a mistyped or truncated secret. A secret lasts 90 days by default. Use `--expires-in-days` to choose between 1 and 365 days. Each service account can hold two unexpired secrets, so you can create a new one before you delete the old one.

Set the secret as `ENTIRE_TOKEN`. The `entire` CLI, `git-remote-entire`, and the Go SDK exchange it for a service account token and renew that token as needed:

```bash theme={null}
export ENTIRE_TOKEN="$(cat deploy.secret)"
entire repo clone /et/acme/web
```

Any other HTTP client exchanges the secret itself. Send it to the auth URL for the project's region as the subject of an RFC 8693 token exchange, with the service account ID as the `resource`:

```bash theme={null}
TOKEN=$(curl -sS -X POST "https://us.auth.entire.io/oauth/token" -u "entire-cli:" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token=$ENTIRE_TOKEN" \
  --data-urlencode "audience=https://us.auth.entire.io" \
  --data-urlencode "resource=svc_<ULID>" \
  | jq -r '.access_token // error(.error_description)')
```

The response has the service account token in `access_token` and its lifetime in seconds in `expires_in`. A token from a secret lasts at most 10 minutes, and never past the secret's own expiry. Send the token as a bearer, never the secret itself. Exchange the secret again when the token nears expiry or after a `401`.

`entire service-account secret list acme/deploy` shows each secret's expiry and last use. `entire service-account secret delete acme/deploy <secret-id>` revokes one. It can no longer be exchanged, and tokens already exchanged from it expire within 10 minutes.

## Continue With

> [card] [service-account](https://docs.entire.com/cli-reference/service-account.md)
>
> See every `entire service-account` command and flag.

> [card] [OpenID Connect (OIDC)](https://docs.entire.com/guides/configuration/oidc.md)
>
> Let a platform's jobs sign in with their own token.

> [card] [Troubleshooting](https://docs.entire.com/guides/configuration/service-accounts-troubleshooting.md)
>
> Fix access, sign-in, and secret errors.