# 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

```sh
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.

```sh
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](https://sailfork.com/docs/api#authentication).
- **The CLI.** `sailfork auth login` creates and stores one for you. See [the CLI token](#the-token-the-cli-stores).
- **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](https://sailfork.com/docs/mcp).

SSH keys are separate. They authenticate git over SSH only. See [Git access](https://sailfork.com/docs/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 <name> 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

```sh
sailfork token list
sailfork token create ci-readonly --scopes repo:read --expires 90d
sailfork token delete <id>
```

| Command | Flags |
| --- | --- |
| `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.

| Scope | Allows |
| --- | --- |
| `repo:read` | Clone, fetch and read issues, pull requests and CI runs |
| `repo:write` | Push, open and merge pull requests, edit issues, rerun CI |
| `repo:admin` | Create and delete repositories, change branch protection and CI secrets |
| `user` | Read and update your profile, SSH keys and tokens |
| `org:read` | See your organizations, members and teams |
| `org:admin` | Create organizations; manage members, teams, rules, domains, CI providers and Drydock hosts |
| `sandbox` | Start 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](https://sailfork.com/docs/permissions#how-token-scopes-narrow-a-role).

### 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.

```sh
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.

```sh
sailfork whoami
sailfork auth token
sailfork auth status
sailfork auth logout
```

| Command | What it does |
| --- | --- |
| `sailfork whoami` | Prints 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 token` | Prints the token for the current host. |
| `sailfork auth status` | Shows who you are signed in as on each host. |
| `sailfork auth logout` | Revokes this machine's token and forgets it. |
| `sailfork auth setup-git` | Makes `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](https://sailfork.com/docs/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](https://sailfork.com/docs/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](https://sailfork.com/docs/ci).

---

Every docs page: https://sailfork.com/llms.txt
