Authentication

Every route takes a personal access token as a bearer credential. It is the only credential that a person creates. The same token authenticates curl, the CLI and an agent that acts for you:

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

When you create a token, you set three limits on it. The scope set controls what it may do, an optional project pin controls where, and the expiry controls how long it lasts.

Creating a token

In the console

Open Settings → API tokens in the console. Give the token the name of the place where you will use it. Later, the name tells you which token to revoke. Then choose an access level for each resource, not individual scopes.

The levels are the ones in Permissions below. A level that grants a write scope also grants the read scope that the write implies, so you cannot grant half of a permission.

Two more fields limit the token. Project pins the token to one project. The token can then read and act on that project only, and on nothing across the organization. This is the narrowest useful grant for a third-party integration. Expiry is 90 days by default and one year at most. You cannot create a token that never expires.

The console shows the token once, when you create it. SHIP stores only a hash of the token, so nobody can recover a lost token. If you lose a token, create a new one and revoke the old one.

Over the API

POST /v1/tokens mints a token only from a signed-in console session. If a call sends a bearer token, the API refuses it with 403. So no token can give itself more access, and a token pinned to one project cannot mint an organization-wide token. Create tokens on the Settings → API tokens page in the console. The page sends a request with this body:

{ "name": "ci", "scopes": ["missions:run", "missions:read"], "expiresInDays": 30 }

The raw token appears only in this response. After that, GET /v1/tokens lists your own tokens with their identity and lifecycle data, but never the secret. DELETE /v1/tokens/{tokenId} revokes one of them.

Using it

The CLI reads the same variable, so one export works for curl and for the CLI:

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

What a token cannot do

• Exceed the person who created it. Each requested scope must be within the creator's own grant ceiling. A token is delegated authority, so it can never carry more than its creator holds. The API refuses a request above the ceiling and names each refused scope. It does not silently drop those scopes and mint a narrower token.
• Outlive its expiry. Every token expires.
• Be recovered. Create a new token, and revoke the old one.
• Survive revocation anywhere. A revocation applies to every later request. You do not need to redeploy anything.

Permissions

Each scope has the form resource:action, and scopes are what the token stores. The tables below group the scopes into ordered access levels, because you choose a level for each resource, not individual scopes. Each level grants exactly the scopes in its row. Every resource also has No access, which is the default.

The minimum role column shows the organization role that a person needs to delegate that level. A level marked gates no public route yet exists, and you can mint it, but it 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. Stopping one ends the agent's work before it finishes.

Scheduled tasks

Scheduled tasks 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 model spend today.

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 complete grant for one job. It lists the scopes to request and, where that matters more, the scopes to leave out.

A CI job that hands work over

missions:run missions:read

The job files a mission when a build needs follow-up work, then polls the mission until it has a verdict. Pin the token to the project whose pipeline runs the job, and the token can reach nothing else.

Leaves out missions:write, because an unattended job should not be able to pause, stop or re-instruct a mission that someone monitors.

A coding agent that delegates a branch

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

The CLI needs this set. With it, the CLI hands over a plan or a pull request (missions:run) and follows the mission (missions:read). It also sends follow-up instructions (missions:write) and reads the proof that the mission produced (artifacts:read).

Leaves out agents:write, because the dispatch itself carries the harness and model for one delegated mission. A change to the project's default execution config is a separate authority that the agent does not need.

A reporting dashboard

missions:read projects:read scheduled-tasks:read orchestrator:read agents:read

This set has everything that a dashboard of cost and outcomes needs, and no scope that spends money. The orchestrator:read scope includes the model spend for the day, and agents:read shows which harness and model produced each result.

Leaves out every write scope, so a dashboard that can only read can never start an unexpected run.

On-call: stop a runaway run

missions:read missions:write sandboxes:read sandboxes:stop

Pause or stop a mission, and stop the sandbox that still uses budget for it.

Leaves out missions:run, on purpose. This token exists to stop work, so it should not be able to start work.

Debugging one bad run

missions:read inspect:read artifacts:read

This is the largest read disclosure that the API offers. It covers assembled prompts, provenance, dispatch errors and session logs, but gives no authority to change anything. Mint a new token with a short expiry for each incident, instead of one token that you keep.

Managing scheduled tasks

scheduled-tasks:read scheduled-tasks:write missions:read

Create and change schedules, and read what their runs did. Treat this set as a spend grant, although nothing starts when you use it. A schedule that you write commits spend on every future run that it starts.