# API tokens

A workspace API token lets a script or an agent read your workspace's figures: projects, costs, revenue, renewals and health. Tokens only read, and a token never reads more than the person who made it can read now. This guide covers making a token, keeping track of it, revoking it, and calling the REST API with it. To use a token with Claude Code, Claude Desktop or Cursor, see [Connect your agent](connect-your-agent.md).

## Who can make tokens

Tokens live in **Settings** → **API**, which every member can open.

- **Owner** and **Admin**: make tokens for every project, with or without amounts, and see and revoke every token in the workspace. The page says "Tokens let a script or an agent read this workspace's figures through the API."
- **Editor** (of the whole workspace or of some projects): make tokens for the projects they can see, with amounts only where they see amounts, and see and revoke their own. The page says "Your tokens for scripts and agents. … Owners and admins see every token."
- **Viewer**: can't make tokens. With none to show, the page says "No API tokens yet" and "Owners, admins and editors create API tokens."

## Make a token

1. Open **Settings** in the sidebar, then **API**.
2. Press **Create token**. With no tokens yet, it's under "No API tokens yet"; otherwise it's at the top of the page.
3. The **Create an API token** dialog opens. Under **Name**, type something you'll recognise later, like "Claude Code on my laptop".
4. **Access** says **Read only**: "Tokens read figures; they can't change anything." There is nothing to choose.
5. Under **Projects**, keep **All projects** ("Every project you can see, including ones added later.") or choose **Chosen projects** and tick the ones the token may read under **Choose projects**.
6. Tick **Include amounts** if the token should see revenue, costs and other money. Without it, amounts are hidden. If you can't see amounts for the projects you chose, the box is off and says "You can't see amounts for these projects, so neither can a token."
7. Under **Expires**, keep **In 90 days** or choose **In 30 days**, **In 1 year** or **Never**.
8. Press **Create token**.
9. If you haven't signed in recently, ShipVitals asks you to **Confirm it's you** first ("Creating an API token needs a recent sign-in."). Once you have, the dialog opens again as you left it; press **Create token** again.

**Create token** stays off until the token has a name and, with **Chosen projects**, at least one project.

If the token can't be made, the dialog says why, for example "Too many tokens in the last hour. Try again later." Every plan includes API tokens, with no limit on how many.

## Copy it once

The dialog becomes **Your new API token**, with the line "This is the only time you'll see it."

1. Press **Copy token** beside **Token**, and keep it somewhere safe, such as your password manager or your script's secret store.
2. Under it, "Send it as a bearer token: Authorization: Bearer <token>." To use it with an agent, **Connect your agent with it** shows the setup snippets with the token already filled in (see [Connect your agent](connect-your-agent.md#add-it-to-your-agent)).
3. Press **I've stored it**.

Once the dialog closes, the token can't be shown again. If you lose it, revoke it and make a new one.

## The token list

Each token has a row in **Settings** → **API**:

- Its name and its last four characters, like `sv_api_…3f9a`, so you can tell which one a script holds.
- What it reads: "Read only · All projects · With amounts", or the projects by name and **No amounts**.
- Who made it and when ("Created by you 3 days ago", or "Created by Dana 3 days ago" for an owner or admin looking at someone else's), when it was last used, and when it expires: "Last used 2 minutes ago from claude-code · Expires Feb 10, 2027" (or "Never expires"). An agent's row names the agent as it introduces itself; a script's names the program in its User-Agent, like "Last used 2 minutes ago from curl". A request with no User-Agent says only "Last used 2 minutes ago". A token that hasn't been used says "Never used".

## Revoke a token

1. Press **Revoke** on the token's row. There is no question first.
2. The token stops working at once, and the page says "… revoked. Anything using it stops working now." with **Undo**.
3. To bring it back, press **Undo** within 10 seconds: "… works again." After that, make a new token instead.

When someone leaves the workspace, their tokens stop working too.

## A token never reads more than its creator

Every request reads with the token's creator's access as it is now, narrowed to the projects and amounts the token was given:

- Narrow someone's access (fewer projects, or no amounts) and their tokens narrow with it at the next request, even an owner's or an admin's token.
- A token for **All projects** reads the projects its creator sees when it's used, including new ones.
- A token without amounts answers with the amounts left out.

## Call the REST API

The API is read only and answers JSON. Send the token in the `Authorization` header:

```
curl -H "Authorization: Bearer sv_api_…" "https://shipvitals.com/api/v1/public/portfolio?period=30d"
```

Put your token in place of `sv_api_…`. Keep it out of the address and out of your shell history where you can, for example by reading it from an environment variable.

The endpoints:

| Endpoint | What it answers |
|---|---|
| `GET /api/v1/public/projects` | The projects this token reads. |
| `GET /api/v1/public/portfolio` | The portfolio's figures and projects for a period. |
| `GET /api/v1/public/projects/{projectId}/summary` | One project's figures for a period. |
| `GET /api/v1/public/costs` | Costs by provider, service or project for a period (`group=provider`, `service` or `project`). |
| `GET /api/v1/public/revenue` | Revenue, MRR movements and each project's share for a period. |
| `GET /api/v1/public/obligations` | Renewals and expiries due soon (`days=`, up to 90). |
| `GET /api/v1/public/health` | Uptime, checks and incidents for a period. |
| `GET /api/v1/public/incidents` | Open or recent incidents (`status=open`, `resolved` or `all`). |

Periods are `period=7d`, `30d` (the default), `90d`, `12m`, `mtd`, `qtd` or `ytd`, or `period=custom` with `from=` and `to=` days (`YYYY-MM-DD`). Most endpoints also take `project=` with a project's id from `/projects`. Amounts are whole numbers in the currency's minor units (cents).

The full reference, with every parameter, field and error, is at [/docs/api](https://shipvitals.com/docs/api), drawn from the OpenAPI document the API serves at `/api/v1/openapi.json`.

### Answers that aren't 200

- **400**: a parameter it can't read, such as `period=custom` without `from` and `to`.
- **401**: no token, or one that is unknown, expired, revoked, or beyond its creator's access now.
- **403**: the workspace is suspended.
- **404**: a project this token doesn't read, or one that doesn't exist.
- **429**: more than 60 requests in a minute. `Retry-After` says when to try again.

## Limits

A token makes up to 60 requests a minute, shared between the REST API and the MCP server. A token works only with the API and the MCP server: it can't sign in to ShipVitals or be used anywhere else in it.

ShipVitals keeps only a hash of each token, never the token itself. See [/security](https://shipvitals.com/security) for how tokens are protected.
