Authentication

The typeship API accepts organization API keys and delegated OAuth access tokens. An API key identifies one account 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

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 the active organization, 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/me \
  -H "Authorization: Bearer ak_..."

A missing or invalid credential returns 401 with the code unauthorized. 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 reads 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 /v1/generate is the one operation that works anonymously. Leave the Authorization header off and it behaves like the generator on the homepage: the first 25 operations of the Definition, rate limited per IP address, with no Definition contents or generated files retained. The response carries a limits object naming what was held back and where to sign up. For a URL Definition, typeship retains a seven-day claim recipe (URL, Target, config, summary, and opaque token) and returns its claim.url; once a person signs in, that link turns the recipe into a Project in their organization. Inline and authenticated calls create no claim. That is the front door for a script or an agent that has a Definition and no account yet. A key that is present but invalid is a 401, never a silent downgrade to anonymous. Everything else needs a key.

Rotate and revoke

List keys with GET /v1/api_keys and revoke one with DELETE /v1/api_keys/{id} (typeship api-keys list, typeship api-keys revoke <id> --force), or use revoke in the console. 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.

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 have the full permissions of the account, 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