# 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://mn.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 unless you limit it under **Repository access**; **Customize these permissions** opens it in the custom builder to narrow it. ### Custom permissions The custom builder lists each resource once: Repositories, Branches, Pull requests, Issues, Comments, Organizations, Teams, Tokens & keys and Personal profile. Each resource has one level, **No access**, **Read**, **Write** or **Admin** (whichever apply; Comments' highest is **Moderate**, Tokens & keys has only **Manage**): | Resource | Read | Write | | ------------- | ------------------------------- | --------------------------------------------- | | Repositories | Code and repository metadata | Push code, upload attachments, read metadata | | Branches | Branch rules | Branch rules (pushing is Repositories) | | Pull requests | Pull requests and their reviews | Open and edit your own, leave comment reviews | | Issues | Issues | Open issues and edit your own | | Comments | Comments | Write comments and edit your own | | Organizations | Profile and members | Profile, webhooks; members read | | Teams | Teams and their members | Teams, their members and repository grants | **Admin** is every permission of that resource at its highest level. **Details** under each resource lists its exact permissions, with a line for the ones people confuse: approving (counts toward required approvals, as a person's does) is separate from leaving a review and from dismissing one; **Edit others'** changes what other people wrote; **Code & contents** is the repository's code, while a branch's **Contents** are branch rules. Changing a permission there marks the resource **Custom**. Branches and pull requests can also be limited there with **Applies to**: branches matching a pattern such as `release/*`, or pull requests targeting a branch. ### Repository access Under **Repository access**, choose **All repositories you can access** (the default) or **Only select repositories…** and tick them. A limited token holds each repository permission (repositories, branches, pull requests, issues and comments) once per selected repository; organization, team and account permissions are not limited by repositories. Repositories created later are never added. A token holds at most 100 permissions, so the more permissions you choose, the fewer repositories it can be limited to (at most 50); the form shows the limit. 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://mn.staging.git.cafe/docs/account/account-settings.md#confirm-its-you).