Tokens and MCP clients

The Tokens API manages the credentials that authenticate you to Openship: personal access tokens (PATs) for the CLI and direct API calls, and the MCP client bindings created when an AI assistant connects over OAuth. In the dashboard this is the Settings → Access area; from the terminal it's the openship token command. Every route is self-scoped — you only ever see and manage your own tokens and clients.

Create a token

Mints a new PAT and returns the plaintext secret in data.token exactly once — it is hashed at rest and can never be retrieved again. List responses only ever show the short tokenPrefix.

const result = await ship.tokens.create({
  name: "deploy-bot",
  readOnly: false,
  grants: [
    {
      resourceType: "project",
      resourceId: "proj_123",
      permissions: ["read", "write"],
    },
  ],
});
console.log(result);

curl -X POST "$OPENSHIP_URL/api/tokens" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy-bot","readOnly":false,"grants":[{"resourceType":"project","resourceId":"proj_123","permissions":["read","write"]}]}'

Each entry in grants is a TokenGrant:

The "projects it creates" scope

To hand an agent (e.g. an MCP client) the ability to create new projects and fully manage only the ones it creates — with zero visibility into anything else — give it a single create grant on the project collection:

{ "name": "agent", "grants": [{ "resourceType": "project", "resourceId": "*", "permissions": ["create"] }] }

create is collection-only: it authorizes POST /api/projects and lets the token list projects (filtered to its own), but grants no read/write/admin on any existing project. Each project the token creates auto-adds a { project, <id>, [read, write, admin] } grant, so it fully controls its own work and nothing else. In the dashboard this is the "Only projects it creates" option on the MCP authorize screen.

List tokens

const tokens = await ship.tokens.list();
console.log(tokens);

curl "$OPENSHIP_URL/api/tokens" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Returns your tokens with no secret material — each row carries id, name, tokenPrefix, readOnly, scoped, expiresAt, lastUsedAt, revokedAt, and createdAt.

Revoke a token

await ship.tokens.revoke("pat_123");

curl -X DELETE "$OPENSHIP_URL/api/tokens/pat_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

MCP clients

When an AI assistant connects to Openship over OAuth, the consent page records what that client is allowed to do, then Openship issues it scoped access tokens that run through the same scoped-principal path as a PAT. These routes back that flow and the Settings → Access → Connected clients list.

Authorize a client

Called by the OAuth consent page (browser cookie session) before a token is issued. It persists the user's chosen read-only flag and resource grants as the client's binding. Grants are validated ⊆ your own access, identical to token creation. Re-authorizing overwrites the binding's grants wholesale.

POST /api/tokens/mcp-authorize

List connected clients

GET /api/tokens/mcp-clients

Returns one entry per OAuth binding with clientId, name, organizationId, organizationName, readOnly, scoped, grantCount, authorizedAt, and lastUsedAt.

Disconnect a client

Revokes the client's issued tokens first (stopping it immediately), then drops the scope binding, its grants, and the recorded consent so a reconnect re-prompts. Scoped to you — a client shared across users keeps working for everyone else.

DELETE /api/tokens/mcp-clients/:clientId

Operations