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 login is
usually simpler: it handles Git credentials for you.
Create a token
- Choose Generate new token.
- Under What is this token for?, pick a template or Custom. Nothing is selected until you choose.
- 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.
- 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.
- 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:
| 1 | 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.