REST API access

The REST API under /v1 offers the same capabilities as the account MCP connection: find tools, run and build them, follow jobs, and manage saved logins and API keys. It accepts two kinds of bearer credential in the Authorization: Bearer header.

OAuth access tokens

An access token your MCP client obtained for the account MCP endpoint also works on /v1. It carries the same authorization: the permissions you granted, your account’s current role and the same jobs. A job started through MCP can be read and cancelled through /v1, and the other way round.

Request the token for the account MCP endpoint’s exact URL as its resource. There is no separate /v1 resource.
An unauthenticated /v1 request returns 401 with a WWW-Authenticate header whose resource_metadata names the account MCP endpoint’s protected-resource metadata. See authentication.
A token for an individual integration’s MCP endpoint does not work on /v1.

API keys

An API key is a long-lived credential for programs that cannot complete an OAuth flow. Keys start with pom_. Each key belongs to you and to one account.

Key type	Can carry	Reaches
Account key	Any of your permissions: tools, usage, builds, runs, jobs, saved logins	Every `/v1` route those permissions allow
Integration key	Only finding and running tools and following jobs (`tools:read`, `runs:create`, `jobs:read`, `jobs:cancel`)	One integration’s tools, its runs and the jobs it started

Create keys on the Dashboard’s Settings → API keys page, or with POST /v1/api-keys from a signed-in session. Creating or rotating a key needs a sign-in within the last five minutes.
The secret is shown once. Store it in a secret manager; Pomerado keeps only a digest and cannot show it again.
A key never holds more than you do: if your role loses a permission, or you leave the account, the key loses it too.
Every key expires, after 1 to 365 days. Rotate a key to replace its secret; the old secret stops working at once.
Revoke a key on the Dashboard, with DELETE /v1/api-keys/{id}, or with the MCP tool revoke_api_key. Requests with it are refused from then on, and jobs it started stop.
An API key cannot list, create or revoke keys, reveal a saved login’s password or read its TOTP code. Those need you signed in.

Key management routes

Route	Result
`GET /v1/api-keys`	`{apiKeys:[...]}`: id, name, permissions, `integrationId`, a hint, created, expires, last used
`POST /v1/api-keys`	`{name, permissions, integrationId?, expiresInDays}` returns `201 {apiKey, secret}`
`POST /v1/api-keys/{id}/rotate`	`{apiKey, secret}` with a new secret
`DELETE /v1/api-keys/{id}`	`{status:"revoked"}`

Response	Next step
`401 unauthorized`	The key is unknown, revoked or expired, or the secret is wrong. Create a new one.
`403 FreshAuthenticationRequired`	Sign in again in the browser, then create or rotate the key within five minutes.
`403 forbidden`	The key, or your role, lacks the permission, or the route is outside an integration key’s integration.
`409 api_key_limit_reached`	Revoke a key first. Each member may hold 50.

Never send an API key or its secret in an MCP message, a URL or a log. Treat it like a password.

Get started

Guides

Reference

OAuth access tokens

API keys

Key management routes

​OAuth access tokens

​API keys

​Key management routes

OAuth access tokens

API keys

Key management routes