> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API tokens and the API

> Reaching Shipways from a script, from CI, or from an assistant.

## Tokens

Issued under **API tokens**, per organization.

A token **acts as the person who created it and can only ever narrow what they
could do**. A developer's read-write token still cannot delete a server,
because a developer cannot.

**Read** sees anything the owner can see. **Write** does anything the owner can
do, including deploying.

An expiry in days is optional. Without one the token lives until it is revoked.

Tokens start `shp_`, so one found in a log or a repository is recognisable as
one — which is what lets scanners and people report it rather than wonder what
it is.

Only a digest is stored. The token is shown **once**, when it is created, and
losing it means issuing another. Revoking one stops whatever was using it
immediately, and it cannot be brought back.

## The API

Versioned in the path: `/api/v1`. An integration written today should go on
working when the shape of a site changes.

**The token carries the organization**, so nothing in the API takes one as a
parameter. A leaked token cannot be pointed at somebody else's servers by
editing a URL.

Rate limited to 120 requests a minute per token by default.

### Read

```
GET  /api/v1/servers
GET  /api/v1/servers/{server}
GET  /api/v1/sites
GET  /api/v1/sites/{site}
GET  /api/v1/sites/{site}/deployments
GET  /api/v1/deployments/{deployment}
GET  /api/v1/alerts
GET  /api/v1/sites/{site}/certificates
GET  /api/v1/sites/{site}/commands/{uuid}
```

### Write

```
POST   /api/v1/servers
PATCH  /api/v1/servers/{server}
DELETE /api/v1/servers/{server}
POST   /api/v1/servers/{server}/sites
PATCH  /api/v1/sites/{site}
DELETE /api/v1/sites/{site}
POST   /api/v1/sites/{site}/deployments
POST   /api/v1/sites/{site}/commands
POST   /api/v1/sites/{site}/certificates
```

Commands and deployments are queued, so both answer with something to poll
rather than with a result.

## Deploying from CI

If all you want is "deploy this site when the build passes", a
[deploy hook](/sites/deployments#the-deploy-hook) is simpler than a token: one
address, nothing to authenticate, nothing to rotate on a schedule.

Use a token when CI needs to read state back — whether the deployment
succeeded, what the alerts say.

## MCP

Shipways exposes an MCP server at `/mcp`, behind the same tokens as the API, so
an assistant can list what you have and deploy it.

The tools are: list servers, list sites, list alerts, deploy a site, and check
a deployment's status.

An assistant reaching this can do exactly what the token's owner could do in
the panel. The tools authorize through the ordinary policies rather than
trusting that having got this far means anything: read is enough to look, and
deploying checks for write on top.