> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](authentication.md#oauth-discovery-for-client-developers).
* 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.