Authenticate Percify API requests

Send your Percify key as Authorization: Bearer pk_live_… on every request. How to create, test, cap, regenerate and revoke API keys.

Percify authenticates API requests with a secret key that starts with pk_live_. Send it in the Authorization header as a Bearer token on every call to api.percify.io. You create keys on the developer page at app.percify.io/home/developer, on the Scale and Ultra plans.

The header

Authorization: Bearer pk_live_your_key_here

Keep the key in an environment variable. The code on this site uses PERCIFY_API_TOKEN, the same name the developer page’s snippets use:

export PERCIFY_API_TOKEN="pk_live_…"

Test a key without spending credits

POST /v1/estimate checks your key and prices a run, and it never charges:

curl -s -X POST https://api.percify.io/v3/playground/v1/estimate \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"gpt-image-2","input":{"prompt":"a red bicycle on a white wall"}}'

A working key returns 201 with data.credits. A missing or wrong key returns 401.

Create, cap and expire keys

1. Open API Access

   In the Percify app, open the account menu at the bottom of the sidebar and choose API Access.

2. Fill in the key form

   Click New key. Name (optional) helps you tell keys apart. The expiry list offers Never expires, Expires in 30 days, Expires in 90 days and Expires in 1 year. Monthly credit cap limits what this one key can spend in a calendar month; leave it empty for no per-key limit.

3. Create and store it

   Click Create key and copy the key. It is shown once and Percify does not store the full key, so a lost key cannot be recovered. Create a new one instead.

Each key in the list shows its credits used this month against its cap, when one is set, and its expiry date.

Regenerate or revoke a key

• Regenerate creates a new key with the same name and monthly cap, then disables the old key. Update your servers with the new key right away.
• Revoke disables a key. The next request with it returns 401 with Invalid, expired, or revoked API key.

Use one key per app or environment. Then you can revoke one leaked key without breaking everything else, and each key’s cap limits what a leak can spend.

What the 401 errors mean

Message	Cause
Missing credentials. Use: Authorization: Bearer pk_live_... (API key) or an OAuth access token.	No Authorization: Bearer … header was sent.
Missing API key. Use: Authorization: Bearer pk_live_...	The value starts with pk_ but has characters a key never contains, such as a trailing quote.
Invalid, expired, or revoked API key	The key is wrong, past its expiry, or revoked.
Invalid or expired OAuth access token	A non-pk_ Bearer token that is not a valid Percify OAuth token.

Every 401 also carries a WWW-Authenticate: Bearer resource_metadata="…" header. MCP clients read it to find the sign-in flow; your own code can ignore it.

API keys or OAuth?

Use	Credential
Your server, scripts, Claude Code, Cursor, Codex	A pk_live_ API key
Claude custom connectors and other MCP clients that sign in through the browser	OAuth: you sign in to Percify and approve the connection, no key needed

OAuth tokens use the same account and the same credits as your API keys. The authorization server is https://api.percify.io; its metadata is at api.percify.io/.well-known/oauth-authorization-server and supports dynamic client registration with PKCE (S256). Setup for each client is on the MCP server page.

Keep keys safe

• Never put a key in browser or mobile app code. Call Percify from your server.
• Do not commit keys to git. Use environment variables or a secret manager.
• Set a Monthly credit cap on keys used by automations.
• If a key leaks, revoke it on the developer page.

Related

API overview

Base URL, endpoints and which plans include API keys.

Errors and rate limits

Every status code and what to do about it.

Code examples

Authenticated calls in Node.js, Python and cURL.

MCP server

Connect Claude, ChatGPT, Cursor or Codex.