Authentication

Every route takes a personal access token as a bearer credential. It is the only credential a person creates, and the same one authenticates curl, the CLI and an agent acting on your behalf:

curl -H "authorization: Bearer $SHIP_API_TOKEN" https://api.letsship.ai/v1/missions

Three things bound a token, all chosen when you create it: a scope set for what it may do, an optional project pin for where it may do it, and an expiry for how long it lasts.

Creating a token

In the console

Settings → API tokens. Name the token after the place it will live: the name is what you read when deciding which one to revoke. Then choose an access level per resource rather than individual scopes. The levels are the ones under Permissions below, and they grant a write only together with the read it implies, so a half-granted permission is not one of the options.

Two fields narrow it further. Project pins the token to a single project, after which it can read and act on that project alone and nothing org-wide, which is the narrowest useful grant for anything third-party. Expiry defaults to 90 days and is capped at a year; there is no non-expiring option.

The token is displayed once, at creation. Only a hash of it is stored, so a token that is lost is replaced by creating a new one and revoking the old, never recovered.

Over the API

Minting needs a credential already, so the first token comes from the console. After that, POST /v1/tokens mints more, from a console session or from a token that can reach the route:

curl -X POST https://api.letsship.ai/v1/tokens \
  -H "authorization: Bearer $SHIP_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"ci","scopes":["missions:run","missions:read"],"expiresInDays":30}'

The response is the only place the raw token ever appears. GET /v1/tokens lists your own tokens afterwards, showing identity and lifecycle only and never the secret, and DELETE /v1/tokens/{tokenId} revokes one of them.

Using it

The CLI reads the same variable, so exporting it once covers both surfaces:

export SHIP_API_TOKEN=pat_...
ship status SHIP-412

What a token cannot do

• Exceed the person who created it. Every requested scope must be within the creator's own grant ceiling, because a token is delegated authority and can never carry more than its creator holds. An over-ceiling request is refused naming each entry, never quietly narrowed to the permitted subset.
• Outlive its expiry, which is always finite.
• Be recovered. Replace it, and revoke what it replaced.
• Survive revocation anywhere. Revoking takes effect for every subsequent request; nothing needs redeploying.

Permissions

A scope is named resource:action and is what the token actually stores. They are grouped into ordered access levels because that is the shape of the decision. Each level grants exactly the scopes listed against it, and every resource additionally offers No access, which is the default.

The minimum role column is the org role somebody must hold to delegate that level at all. A level marked gates no public route yet is real and mintable but currently authorizes nothing.

Missions

Missions, their runs, verdicts and cost. Writing lets the holder pause, resume, stop and instruct.

Mission dispatch

Starting a mission and creating new ones. This spends money on agent runs, so it is separate from operating a mission that already exists.

Mission inspection

The forensic report for a mission: assembled prompts, provenance, dispatch errors and session logs. A larger disclosure than the board, so it is its own permission.

Projects

Projects and their settings. Writing can create, change and delete them.

Organization

Organization details and who belongs to it. Writing can invite teammates and change memberships.

Organization creation

Creating new organizations. Separate from managing the one this token belongs to.

Credentials

Connected accounts and stored keys. Reading lists them and never exposes a secret value; writing can connect, update and remove them.

Sandboxes

Running agent sandboxes and their metrics. Terminating one stops work that is in flight.

Automations

Scheduled automations and their run history. Writing one commits spend on every future run it fires, not just once.

Artifacts

Proof-of-work artifacts: screenshots, traces and reports. These can contain repository content.

Preview environments

Preview environments and their status. Writing can create and tear them down.

Agent configuration

Which harness and model each role runs on. Writing changes what every future run costs, because switching a role to a larger model is roughly a 5x cost decision.

Orchestrator

The orchestrator's model, its inference setting and the organization's daily spend cap. Writing can raise that cap.

API tokens

Revoking API tokens belonging to the organization. Operator tokens only; a personal token cannot.

Scope sets for common integrations

Each set below is the whole grant for one job: what to ask for, and, where it matters more, what to leave out.

A CI job that hands work over

missions:run missions:read

Files a mission when a build needs follow-up work, then polls it until it reaches a verdict. Pin it to the project whose pipeline it runs in and nothing else is reachable.

Leaves out missions:write, because an unattended job should not be able to pause, stop or re-instruct a run somebody is watching.

A coding agent delegating a branch

missions:run missions:read missions:write artifacts:read

What the CLI needs: hand over a plan or a pull request (missions:run), follow it (missions:read), send it follow-up instructions (missions:write), and read the proof a run produced (artifacts:read).

Leaves out agents:write, because the harness and model for one delegated mission travel in the dispatch itself, so changing the project's standing execution config is a separate authority the agent does not need.

A reporting dashboard

missions:read projects:read automations:read orchestrator:read agents:read

Everything a cost-and-outcome readout needs and nothing that spends. orchestrator:read carries the daily spend cap and the day's spend against it; agents:read says which harness and model produced each result.

Leaves out every write scope, so a dashboard that can only read can never be the thing that started a surprise run.

On-call, stopping a runaway run

missions:read missions:write sandboxes:read sandboxes:kill

Pause or stop a mission and terminate the sandbox still burning budget behind it.

Leaves out missions:run, deliberately. The point of this token is to stop work, so it should not be able to start any.

Debugging one bad run

missions:read inspect:read artifacts:read

The largest read disclosure the API offers, covering assembled prompts, provenance, dispatch errors and session logs, with no authority to change anything. Worth minting per incident with a short expiry rather than keeping one around.

Managing recurring automations

automations:read automations:write missions:read

Create and adjust schedules, and read what their runs did. Treat it as a spend grant even though nothing starts at the moment you use it: writing a schedule commits spend on every future run it fires.