# Tokens and MCP clients
URL: https://openship.io/docs/api/tokens.md

Create scoped access tokens and manage MCP client consent.

import { TypeTable } from 'fumadocs-ui/components/type-table';

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`](/docs/cli/access) 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`.

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

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

</Tab>
<Tab value="REST API">

```bash
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"]}]}'
```

</Tab>
</Tabs>

<TypeTable
  type={{
    name: { type: 'string', description: 'Human label for the token (1–100 chars).', required: true },
    readOnly: { type: 'boolean', description: 'Read-only tokens reject mutation methods (POST/PUT/PATCH/DELETE).', default: 'false' },
    expiresInDays: { type: 'integer', description: 'Expire the token N days from now (1–365). Omit for a non-expiring token.' },
    grants: { type: 'TokenGrant[]', description: 'Resource scope. When present and non-empty, the token is restricted to exactly these resources — even below the minter’s own role. Each grant must be within the minter’s own access, or the request is rejected.' },
    fullAccess: { type: 'boolean', description: 'Deliberately mint an UNSCOPED token that acts with your own full access. Required when grants is empty or omitted; sending both is rejected.' },
  }}
/>

<Callout title="Scope must be stated, not inferred" type="warn">
Send **exactly one** of `grants` (scoped) or `fullAccess: true` (unscoped). An empty or omitted
`grants` with no `fullAccess` returns `400 TOKEN_SCOPE_REQUIRED`; sending both returns
`400 AMBIGUOUS_TOKEN_SCOPE`.

Openship used to treat an empty `grants` as full access. That made "I want no limits" and "my scoped
selection came out empty" the same request — and it failed open for the dangerous one, so a caller
that meant to restrict a token could silently receive full access. Intent is now explicit.
</Callout>

Each entry in `grants` is a **TokenGrant**:

<TypeTable
  type={{
    resourceType: { type: 'string', description: 'One of: project, server, mail_server, backup_destination, billing, audit, github_installation, github_repository.', required: true },
    resourceId: { type: 'string', description: 'The resource id. For github_repository use "owner/repo".', required: true },
    permissions: { type: '("read" | "write" | "admin" | "create")[]', description: 'Actions the token may take on the resource. "create" is a collection-only capability — see the "projects it creates" scope below.', required: true },
  }}
/>

<Callout title="Copy the secret immediately" type="warn">
The response's `data.token` (an `opsh_pat_…` string) is shown once and never again. `GET /api/tokens` only
returns the prefix. If you lose it, revoke the token and mint a new one.
</Callout>

<Callout title="A token can never exceed its minter" type="info">
Every grant is validated against your own access before the token is created. An unknown `resourceType`
returns `400 INVALID_RESOURCE_TYPE`; granting access you don't hold yourself returns `403 GRANT_EXCEEDS_ACCESS`.
</Callout>

### 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:

```json
{ "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

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

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

</Tab>
<Tab value="REST API">

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

</Tab>
</Tabs>

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

## Revoke a token

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

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

</Tab>
<Tab value="REST API">

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

</Tab>
</Tabs>

<Callout title="404 — token not found" type="error">
The `:id` isn't one of your own tokens (or was already removed). List your tokens with `GET /api/tokens`
to get valid IDs.
</Callout>

## 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
```

<TypeTable
  type={{
    clientId: { type: 'string', description: 'The OAuth client to bind. Required.', required: true },
    readOnly: { type: 'boolean', description: 'Confine the client to read-only access.', default: 'false' },
    organizationId: { type: 'string', description: 'Organization the client is confined to. Defaults to the active org; a different org must be one you belong to.' },
    grants: { type: 'TokenGrant[]', description: 'Resource scope, same shape as token grants. Non-empty binds the client to exactly these resources.' },
    fullAccess: { type: 'boolean', description: 'Deliberately record an UNSCOPED binding — the client acts with your own role. Required when grants is empty; sending both is rejected.' },
  }}
/>

<Callout title="Consent errors" type="warn">
Missing `clientId` returns `400 CLIENT_ID_REQUIRED`; an `organizationId` you're not a member of returns
`403 ORG_NOT_A_MEMBER`. Invalid or over-broad grants fail the same way as token creation
(`400 INVALID_RESOURCE_TYPE` / `403 GRANT_EXCEEDS_ACCESS`).

Scope intent is explicit here too: an empty `grants` without `fullAccess: true` returns
`400 TOKEN_SCOPE_REQUIRED`, and sending both returns `400 AMBIGUOUS_TOKEN_SCOPE`. An unscoped binding
lets the client act with your own role, so it can never be reached by omission.
</Callout>

### 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

{/* api-operations:start */}

| Operation | SDK | REST API |
| --- | --- | --- |
| List your tokens without exposing their secrets. | `tokens.list()` | `GET /api/tokens`<br />`settings:read` |
| Create a token; its secret is returned once. | `tokens.create(input)` | `POST /api/tokens`<br />`settings:write` |
| Authorize or explicitly re-scope an MCP client binding. | `tokens.authorizeMcpClient(input)` | `POST /api/tokens/mcp-authorize`<br />`settings:write` |
| List your authorized MCP clients. | `tokens.listMcpClients()` | `GET /api/tokens/mcp-clients`<br />`settings:read` |
| Revoke a token by its token ID. | `tokens.revoke(id)` | `DELETE /api/tokens/:id`<br />`settings:write` |
| Read one MCP client authorization. | `tokens.getMcpClient(id)` | `GET /api/tokens/mcp-clients/:clientId`<br />`settings:read` |
| Revoke an MCP client authorization. | `tokens.disconnectMcpClient(id)` | `DELETE /api/tokens/mcp-clients/:clientId`<br />`settings:write` |

{/* api-operations:end */}