Authentication

The Typeship API accepts organization API keys and delegated OAuth access tokens. An API key identifies one Organization and has its complete authority. OAuth is the least-privilege path for a person signing an MCP client or another application into Typeship.

Create a key

Only an admin of the organization can create or approve an API key. Members can use OAuth, which preserves their permissions.

In the console under api keys, name the key and choose create key. The full key is shown once. Copy it then; afterwards the console shows the last four characters to tell keys apart.

Or let the Typeship CLI ask for one: typeship login opens the console's approval page, you approve typeship CLI on <host> for an organization where you are an admin, and the API mints the key straight to that machine. The request carries a PKCE-style challenge; the key is handed only to the Typeship CLI that proves the matching verifier, once, and never appears in the browser. Such keys are listed and revoked like any other.

Keys look like this:

ak_7Q2KD4MZX9P1VN6TBH8CRW3JSFY5LAGE

Name keys after where they live (ci, laptop, agent) so revoking one later is a decision, not a guess.

Send it

Every authenticated request carries the key as a bearer token:

curl https://typeship.dev/api/v1/organization \
  -H "Authorization: Bearer ak_..."

A missing credential returns 401 auth_required. An invalid, revoked, or expired API key returns 401 api_key_invalid, and an invalid or expired OAuth access token returns 401 token_invalid. A browser session is not an API credential.

OAuth access tokens

An OAuth access token from a sign-in through Typeship's secured MCP server (/mcp, or any OAuth client registered with Typeship's authorization server) uses the same header: Authorization: Bearer <access_token>. Consent requests an organization scope and three Typeship capabilities:

The consent screen shows what the client requested. The API checks the granted scopes on every call, and the hosted MCP endpoint omits tools outside them. A valid token missing the required capability receives 403 insufficient_scope and a WWW-Authenticate header naming the scope to request.

Scopes never elevate the signed-in person's organization role. Deleting a project requires an organization admin. A member may revoke a key they created; an admin may revoke any organization key. Other forbidden operations receive 403 forbidden even when the token has typeship:write.

The token acts as the user who consented, inside the organization they selected during consent. Typeship checks the verified token's org_id and confirms current membership and role. There is no organization header override, so a grant cannot be reused to move laterally into another organization. Tokens expire on the authorization server's schedule and clients refresh them; revoking the client's grant ends access.

Without a credential

POST /api/v1/generate is the one operation that works anonymously. Leave the Authorization header off and it behaves like the generator on the homepage: 25 operations of the Spec, rate limited per IP address. The response carries coverage with omitted operation counts and a sign-up link when capped. An anonymous URL run without source headers may return claim.url. Open it and sign in within seven days to create a Project in your organization. Inline runs, authenticated runs, and anonymous runs with source headers receive no claim link. See Generate from a URL for the workflow and What is stored for the claim’s contents and lifetime. A key that is present but invalid is a 401, never a silent downgrade to anonymous. Every other API operation requires an API key or OAuth access token.

Rotate and revoke

List keys with GET /api/v1/api-keys, retrieve one with GET /api/v1/api-keys/{id}, and revoke one with POST /api/v1/api-keys/{id}/revoke (typeship api-keys list, typeship api-keys get <id>, typeship api-keys revoke <id> --force), or use revoke in the console. Retrieve a key's ETag and optionally send it in If-Match when revoking. A stale value returns 412 precondition_failed; retrieve the key, confirm you still want to revoke it, and retry with its current ETag. See conditional writes. Revocation takes effect within thirty seconds. Revoked keys stay listed with revoked: true for the audit trail. Rotating means creating a new key in the console, moving it into place, and revoking the old one.

A revoked key stays listed with status: revoked and cannot be restored; filter the list with status=active or status=revoked. Each key records when it was last used, so a key that has gone quiet is easy to spot before you revoke it.

API-key authority

Keys previously created by members, or without an identifiable creator, no longer authorize API requests. Ask an organization admin to create a replacement and update the applications using the old key. Older admin-created keys remain usable while their creator is still an admin; rotate them to an admin-approved machine key for access that remains independent of that person.

Admin-approved machine keys belong to the organization until revoked. Keys have the full permissions of the Organization, no expiry, and no scopes. Treat them like passwords: environment variables and secret stores, never source control. The one thing a key cannot do is create another key. Prefer scoped OAuth when a person is present to consent and the client supports it.

In the tooling