# Personal access tokens

A personal access token lets scripts, CI jobs and tools use the REST API or Git
over HTTPS as you, with only the permissions you grant. Tokens start with
`gct_` and always expire. Manage them at **Settings → Tokens**.

For your own terminal, the [`cafe` CLI](https://staging.git.cafe/docs/getting-started/cli.md) login is
usually simpler: it handles Git credentials for you.

## Create a token

1. Choose **Generate new token**.
2. Under **What is this token for?**, pick a template or **Custom**. Nothing
   is selected until you choose.
3. Check the **Name** (a template fills it in when the field is empty) and
   choose an **Expiration**: 30, 60 or 90 days, or 1 year.
4. Read the summary: **This token will be able to** lists what the token can
   do in plain words, and what it can't do among pushing code and opening,
   reviewing and merging pull requests. **Show permissions** lists every
   permission.
5. Create the token and copy it from the **Token created** dialog.

The token is shown only once. If you lose it, rotate the token or create a new
one.

### Templates

| Template            | Grants                                                                                                                             | Use it for                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Agent / CLI**     | Code (read & write), repository metadata (read), image attachments, pull-request contents, reviews and merges, issues and comments | Coding agents and `cafe` in automation, `cafe pr create`    |
| **CI read-only**    | Code, repository metadata, pull requests, reviews and comments (read)                                                              | CI jobs that clone and inspect pull requests                |
| **Push code**       | Code (read & write), repository metadata (read)                                                                                    | Deploy bots and mirrors that only push; no pull requests    |
| **Manage webhooks** | Repository and organization webhooks (read & write), their metadata (read)                                                         | Tools that register webhooks                                |
| **Org admin**       | Every organization and team permission at its highest level                                                                        | Managing organization settings, members, teams and webhooks |

**Agent / CLI** grants the same permissions as `cafe auth token create`
without `--scope`. Every template applies to all of your resources;
**Customize these permissions** opens it in the custom builder to narrow it.

### Custom permissions

The custom builder lists every resource on one page: Repositories, Branches,
Pull requests, Issues, Comments, Organizations, Teams, Tokens & keys and
Personal profile. Each permission is **No access**, **Read**, **Read & write**
or **Admin**. Branches and pull requests can be limited with **Applies to**:
branches matching a pattern such as `release/*`, or pull requests targeting a
branch.

Permissions are separate per resource. Code access never covers pull requests,
and branch permissions never allow `git push`. The builder warns when:

- the token can push code but can't open pull requests;
- it can open pull requests but can't push code;
- it has branch write permissions but can't push code.
- it can write pull requests, issues or comments but can't attach images to
  them.

Each warning has a button that adds the missing permission. Templates and the
builder only fill in the form: the server checks every request against the
token's permissions.

## Use a token

Send it as a bearer token to the API:

```sh
curl -H "Authorization: Bearer $GITCAFE_TOKEN" https://git.cafe/api/auth/principal
```

That request returns the account the token acts for, which is a quick way to
check a token works.

For Git over HTTPS, enter it as the password when Git asks. With the CLI, set
`CAFE_TOKEN` to use it instead of your stored login.

## Review, rotate or revoke tokens

The list shows each token's name, last eight characters, expiry and a summary
of its permissions; **Show permissions** expands the details. Select a name to
see when it was created and who it acts for.

- **Rotate** replaces the secret, keeping the name, permissions and expiry, and
  shows the new secret once. The old secret stops working.
- **Revoke** ends the token immediately.

Creating, rotating and revoking ask you to [confirm it's
you](https://staging.git.cafe/docs/account/account-settings.md#confirm-its-you).