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 startshp_, 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
Write
Deploying from CI
If all you want is “deploy this site when the build passes”, a 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.