# Sailfork auth.md

Sailfork is a git host for people and AI agents. An agent always acts for a person who has a Sailfork account: there is
no anonymous or self-registered agent identity. Everything an agent does is attributed to that person and the client
it runs in, and the person can see and revoke the access at https://sailfork.com/settings/keys.

## Which credential to use

| You are | Use | Works on |
| --- | --- | --- |
| An MCP client (Claude, Cursor, VS Code, ChatGPT) | OAuth 2.1 sign-in in the browser | `https://sailfork.com/mcp` and the endpoints under it |
| A script, CI job or agent calling the REST API | A personal access token | `https://sailfork.com/api` and git over HTTPS |
| An agent in a terminal | `sailfork auth login` | The CLI and the local MCP server (`sailfork mcp`) |

## OAuth for the MCP server

Discovery follows the MCP authorization spec:

1. A request to `https://sailfork.com/mcp` without a token answers 401 with
   `WWW-Authenticate: Bearer resource_metadata="https://sailfork.com/.well-known/oauth-protected-resource/mcp"`.
2. Protected resource metadata (RFC 9728): https://sailfork.com/.well-known/oauth-protected-resource/mcp names the authorization
   server, https://sailfork.com.
3. Authorization server metadata (RFC 8414): https://sailfork.com/.well-known/oauth-authorization-server.

Register the client in one of two ways:

- **Client ID metadata document.** Use an HTTPS URL that serves your client metadata as the `client_id`. No
  registration call is needed.
- **Dynamic client registration (RFC 7591).** `POST https://sailfork.com/api/oauth/register` with your redirect URIs.

Then run the authorization code grant with PKCE (S256 only). Send the person to `https://sailfork.com/oauth/authorize` with
`resource=https://sailfork.com/mcp` (RFC 8707), and exchange the code at `https://sailfork.com/api/oauth/token`. The access token lasts one
hour and comes with a rotating refresh token. Revoke a token at `https://sailfork.com/api/oauth/revoke` (RFC 7009).

| Scope | Grants |
| --- | --- |
| `mcp:read` | Read repositories, pull requests, issues, CI and caissons |
| `mcp:write` | Also change them: open caissons and pull requests, edit issues, run sandboxes |

At consent the person can grant less than you asked for, such as read-only or a few chosen repositories. An OAuth
token works only on the MCP endpoints.

## Personal access tokens for the REST API

The person creates a token at https://sailfork.com/settings/keys, with `sailfork token create`, or with `POST /api/tokens`.
The secret is shown once. Send it on every request:

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/me
```

A token can also be limited to a list of repositories and given an expiry date.

| Scope | Grants |
| --- | --- |
| `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 |

Full reference: https://sailfork.com/docs/api.md

## From a terminal

```sh
curl -fsSL https://sailfork.com/install | sh
sailfork auth login
```

`sailfork auth login` opens the browser for the person to approve, and also prints a code to enter at
https://sailfork.com/device from another computer. A coding agent should run `sailfork auth login --device --no-wait --json`: it
prints the address and code and returns at once, so the agent can show them to the person, and
`sailfork auth login --resume` finishes once they approve. The agent never sees a password. The token is kept in the
macOS keychain or the Linux secret service; `SAILFORK_TOKEN` overrides it in CI. `sailfork mcp` then serves the same
tools over stdio as that account.

## Errors

- **401**: there is no token, or it expired or was revoked. On `/mcp` the `WWW-Authenticate` header points to the
  metadata to sign in again.
- **403**: the token lacks a scope the route needs, or the repository is outside the token's list.
- **429**: too many requests from this token or address. Wait and retry.
