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.
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
- Open Settings in the sidebar, then API.
- Press Create token. With no tokens yet, it's under "No API tokens yet"; otherwise it's at the top of the page.
- The Create an API token dialog opens. Under Name, type something you'll recognise later, like "Claude Code on my laptop".
- Access says Read only: "Tokens read figures; they can't change anything." There is nothing to choose.
- 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.
- 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."
- Under Expires, keep In 90 days or choose In 30 days, In 1 year or Never.
- Press Create token.
- 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."
- Press Copy token beside Token, and keep it somewhere safe, such as your password manager or your script's secret store.
- 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).
- 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
- Press Revoke on the token's row. There is no question first.
- The token stops working at once, and the page says "… revoked. Anything using it stops working now." with Undo.
- 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
GET /api/v1/public/projects- What it answers
- The projects this token reads.
- Endpoint
GET /api/v1/public/portfolio- What it answers
- The portfolio's figures and projects for a period.
- Endpoint
GET /api/v1/public/projects/{projectId}/summary- What it answers
- One project's figures for a period.
- Endpoint
GET /api/v1/public/costs- What it answers
- Costs by provider, service or project for a period (
group=provider,serviceorproject).
- Endpoint
GET /api/v1/public/revenue- What it answers
- Revenue, MRR movements and each project's share for a period.
- Endpoint
GET /api/v1/public/obligations- What it answers
- Renewals and expiries due soon (
days=, up to 90).
- Endpoint
GET /api/v1/public/health- What it answers
- Uptime, checks and incidents for a period.
- Endpoint
GET /api/v1/public/incidents- What it answers
- Open or recent incidents (
status=open,resolvedorall).
| 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, 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=customwithoutfromandto. - 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-Aftersays 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 for how tokens are protected.