Developer docs

Authentication

API keys, OAuth connections for MCP clients, the Authorization header, limits and security guidance.

Every API request is authenticated with a Bearer token. There are two kinds:

Token	Looks like	For
API key	`pk_live_…`	Your own code: servers, scripts, CI
OAuth access token	`pmo_…`	Apps that connect on your behalf through Sign in with Google — Claude, Cursor, ChatGPT and other MCP clients

text

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Both grant the same /v1/* surface and spend the same credits.

Creating keys

Go to Developers → API keys and click Create key. Give it a name (for example production-backend). The full key is displayed once; afterwards only its prefix is shown. You can have up to 10 active keys and revoke any of them instantly.

Keys are tied to your Poremu account: generations made with a key appear in your library, use your credits and follow your plan's concurrency limit.

Keep keys secret

Never ship a key in a browser, mobile app or public repository. Call the API from your server.
Rotate keys if you suspect exposure: create a new one, deploy it, then revoke the old one.
Keys are stored hashed on our side; we cannot recover a lost key.

Rate limits

Limit	Value
Requests per key	60 per minute
Concurrent generations	Depends on your plan (1 free · 2 Starter · 3 Plus · 5 Pro · 10 Ultra)
Request body	2 MB

When you exceed a limit you receive 429 RATE_LIMITED or 429 CONCURRENCY_LIMIT with a JSON error body. Back off and retry.

API-key and OAuth requests are free up to 1,000 calls per day, then cost 1 credit per 100 calls — see Credits & pricing → API call billing.

OAuth connections (MCP clients)

MCP clients do not need a key: they discover our OAuth 2.1 authorization server and send you to a Poremu consent page in the browser.

Endpoint	Role
`GET /.well-known/oauth-protected-resource`	Resource metadata (RFC 9728) — tells clients where the authorization server is
`GET /.well-known/oauth-authorization-server`	Server metadata (RFC 8414)
`POST /oauth/register`	Dynamic client registration (RFC 7591); public clients only (`token_endpoint_auth_method: none`)
`GET /oauth/authorize`	Authorization code flow; PKCE S256 is required; scope `mcp`
`POST /oauth/token`	`authorization_code` (+ `code_verifier`) and `refresh_token` grants; form-encoded or JSON
`POST /oauth/revoke`	Token revocation (RFC 7009)

Access tokens (pmo_…) live 1 hour; refresh tokens 30 days and rotate on every use. Tokens are stored hashed. Unauthenticated calls to /mcp return 401 with WWW-Authenticate: Bearer resource_metadata="…", which is the signal clients use to start the flow.

Connected apps are listed under Settings → Connected apps (GET /v1/me/connections); disconnecting (DELETE /v1/me/connections/{id}) revokes the token pair immediately.

You normally never build this flow yourself — your MCP client does. If you are writing an MCP client, any standard OAuth 2.1 library with PKCE and dynamic registration works; redirect URIs must be https://…, a loopback http://localhost…, or a custom app scheme.

Testing a key

bash

curl https://api.poremu.ai/v1/me -H "Authorization: Bearer $POREMU_API_KEY"

Returns your account, verification state and balance.