Access tokens

Tokens are the only credential Git and the API accept in normal use.

Scope

Scope	Meaning
ALL_REPO	Every repository you own, including repos created later
SELECTED_REPO	Only the repository ids you list. repository_ids is required

Grants

Grant	What it allows
ALL	Everything below
GIT_HTTP_READ	git clone / fetch
GIT_HTTP_WRITE	git push (read is added if missing)
API_REPOS_WRITE	Create and delete repositories
API_COMMITS_READ	List branches and commits
API_WEBHOOKS	Webhook CRUD, ping, deliveries
API_STORAGE	BYO buckets, verify, error log, oidc-setup
API_OIDC_TRUST	Trust-rule CRUD and setup payload

Listing repositories and reading /v1/account/usage need a valid token, not a special grant.

Minting and listing tokens via API is stricter: the calling token must have grant ALL and scope ALL_REPO.

Note

The website token form exposes Git, commits, webhooks, storage, and OIDC toggles, plus Grant All Permissions. It does not have a separate checkbox for API_REPOS_WRITE. To get that without ALL, create the token through the API.

Create

Web UI

Open Access tokens. For a laptop or agent, keep Grant All Permissions checked.

amendable-cli

amendable token create \
  --name ci \
  --scope ALL_REPO \
  --grants GIT_HTTP_READ,GIT_HTTP_WRITE,API_REPOS_WRITE

The secret prints once.

Listing tokens:

amendable token list

That list call itself needs ALL + ALL_REPO on the calling token.

curl

curl -sS -X POST https://api.amendable.io/v1/access-tokens \
  -H "access-token: $AMENDABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "selected-git",
    "scope": "SELECTED_REPO",
    "grants": ["GIT_HTTP_READ", "GIT_HTTP_WRITE"],
    "repository_ids": ["11111111-1111-1111-1111-111111111111"]
  }'

Limits

Plan	Token ceiling
Free	20
Pro	100

OIDC-exchanged tokens are short-lived (15 minutes) and do not replace this cap the same way a dashboard token does. See OIDC for machines.

Rotate

There is no regenerate endpoint. Create a new token, switch Git remotes and CI secrets, then delete the old id:

amendable token delete 11111111-1111-1111-1111-111111111111

The secret is never returned on GET after create.