Access tokens

Create, scope, limit and revoke the tokens that let git, scripts, the CLI and agents act as you.

Make a token and use it

sailfork token create deploy-bot --scopes repo:read,repo:write --expires 30d --repos fenil/ocean-landing

The command prints the token once. Use it as a password for git over HTTPS, with your handle as the username, or as a bearer token for the API.

git clone https://git.sailfork.com/fenil/ocean-landing.git   # username fenil, password: the token
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/me

The Clone box on each repository's page shows its address. To stop git from asking for a password, run sailfork auth setup-git once.

What a token is for

A token is a secret that acts as your account, limited by its scopes. Four things use one:

  • Git over HTTPS. The username is your handle and the password is the token. A token whose owner is a different handle is refused.
  • The API. Send Authorization: Bearer <token>. See the REST API.
  • The CLI. sailfork auth login creates and stores one for you. See the CLI token.
  • MCP. A local sailfork mcp uses the CLI's token, or SAILFORK_TOKEN. Remote assistants such as Claude or ChatGPT sign in through OAuth instead and never hold a token you made. See MCP.

SSH keys are separate. They authenticate git over SSH only. See Git access.

Create a token in Settings

Open Settings, Keys and tokens, and find Access tokens. Choose New token and fill in:

  • Name. What uses it, like Deploy workflow.
  • Expires. In 7 days, In 30 days (the default), In 90 days or In a year.
  • Scopes. One checkbox per scope. repo:read is ticked at first.

Choose Create token. Sailfork shows the secret once, under the words "Copy now. It is shown once." If you lose it, revoke the token and make another.

The form always sets an expiry and cannot limit a token to certain repositories. The CLI and the API can do both.

Create a token with the CLI

sailfork token list
sailfork token create ci-readonly --scopes repo:read --expires 90d
sailfork token delete <id>
CommandFlags
token list (alias ls)--scope <scope> keeps tokens that carry that scope. --limit <n> caps the rows (default 30).
token create <name>--scopes is a comma-separated list (default repo:read,repo:write). --expires takes a duration such as 8h or 30d, a date YYYY-MM-DD, or an RFC 3339 instant. With no --expires the token never expires. --repos takes owner/repo entries, comma separated.
token delete <id> (aliases revoke, rm)-y or --yes skips the question when there is no terminal. --dry-run says what would happen.

token list prints ID, NAME, SCOPES, EXPIRES and LAST USED.

A name is 1 to 100 characters. A token carries at most 32 scopes and at most 100 repositories.

Scopes

Give a token only what it needs. These are the scopes the token form offers.

ScopeAllows
repo:readClone, fetch and read issues, pull requests and CI runs
repo:writePush, open and merge pull requests, edit issues, rerun CI
repo:adminCreate and delete repositories, change branch protection and CI secrets
userRead and update your profile, SSH keys and tokens
org:readSee your organizations, members and teams
org:adminCreate organizations; manage members, teams, rules, domains, CI providers and Drydock hosts
sandboxStart sandboxes and run commands on your organizations' Drydock hosts

A broader scope includes the narrower ones in its family: repo:write includes repo:read, repo:admin includes both, and org:admin includes org:read. A token that lacks the scope for a route gets a 403 whose message starts insufficient_scope: this token needs. The CLI rewrites it as this token does not have the repo:write scope, with the command that fixes it.

A scope narrows what you can already do. It never adds to it: a token with org:admin still cannot manage an organization you do not own. See Roles and permissions.

Limit a token to repositories

Pass --repos (or repos in the API) and the token reaches only those repositories. Everywhere else it answers 403. You must be able to read every repository you list.

sailfork token create docs-agent --scopes repo:read,repo:write --repos fenil/ocean-landing,acme/site

Tokens that make tokens

Creating a token needs the user scope. A token can make only tokens whose scopes it already has. It also cannot make one that outlives itself: if it expires on a date, the new token must expire by then. Asking for an empty scope list means full access, and only a browser session may do that.

Expiry and revoking

A token stops working at its expiry, and the API then answers 401. The list in Settings shows each token's expiry in red during its last 7 days, and when it was last used and by which agent.

To revoke one, choose Revoke beside it in Settings, Keys and tokens and confirm, or run sailfork token delete <id>. It stops working at once.

Apps you connected through MCP appear under Connected apps, with their own Revoke button. Revoking an app signs it out at once. Connect an app from Settings, Connect an assistant.

The token the CLI stores

sailfork auth login creates a token named CLI on <hostname>. Pass --name to choose another name. Signing in again under the same name replaces that token, so you do not collect old ones.

  • Scopes. Every scope, unless you pass --scopes.
  • Lifetime. 90 days. Run sailfork auth login again when it ends. sailfork doctor shows the days left.
  • Where it lives. In the operating system's keychain. If the keychain is not available, or SAILFORK_NO_KEYRING is set, it is in hosts.toml in the config directory (mode 0600). SAILFORK_CONFIG_DIR moves that directory.
  • Other ways in. sailfork auth login --device skips the browser and prints a code to approve elsewhere. sailfork auth login --with-token reads a token you made from standard input.
sailfork whoami
sailfork auth token
sailfork auth status
sailfork auth logout
CommandWhat it does
sailfork whoamiPrints your handle, name and email, where the token comes from (SAILFORK_TOKEN, keychain or hosts.toml), and the token's scopes, repositories and expiry.
sailfork auth tokenPrints the token for the current host.
sailfork auth statusShows who you are signed in as on each host.
sailfork auth logoutRevokes this machine's token and forgets it.
sailfork auth setup-gitMakes sailfork git's credential helper, so git never asks for a password.

SAILFORK_TOKEN overrides the stored token. The CLI sends it only to the host named by SAILFORK_HOST or SAILFORK_URL, else to the default host.

Warning

Logging in to sailfork.com from a machine replaces the token named CLI on <hostname> for that machine. Any other process using the old token on that machine stops working.

Keep tokens out of logs

  • Do not paste a token into a clone URL such as https://fenil:TOKEN@.... It lands in .git/config and your shell history. Run sailfork auth setup-git instead.
  • Store a token for CI in the CI system's secret store and pass it through an environment variable. Secrets you add under a repository's CI secrets are masked in run logs. See CI.
  • Do not echo SAILFORK_TOKEN or run sailfork auth token in a script whose output is saved.
  • Make one token per use, with a name that says what uses it, so a leak means revoking one token.
  • If a token may have leaked, revoke it now. Settings, Sign-in and sessions has a Security log of token use.

Agents and tokens

Sailfork treats a token with repo:write or repo:admin that has not expired as one of your agents. Work done with it is labeled as agent work when the request names the tool, which the CLI and sailfork mcp do on their own. In Settings, Keys and tokens, the Track agent work switch turns the labels off, so your tokens read as you. Plan limits and the rule that a token cannot approve its own held write still apply. See Agents.

A workflow's GITHUB_TOKEN is separate

A CI job gets its own GITHUB_TOKEN. It reaches only its repository, acts as the person who started the run, follows the workflow's permissions: block and is revoked when the job ends. You never create or see it in Settings. See CI.

Loading Sailfork