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

# 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](https://app.percify.io/home/developer), on the Scale and Ultra plans.

## The header

```http theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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

<Steps>
  <Step title="Open API Access">
    In the Percify app, open the account menu at the bottom of the sidebar and choose **API Access**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](https://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](/mcp-server).

## 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

<CardGroup cols={2}>
  <Card title="API overview" href="/api-reference/introduction">
    Base URL, endpoints and which plans include API keys.
  </Card>

  <Card title="Errors and rate limits" href="/api-reference/errors-and-limits">
    Every status code and what to do about it.
  </Card>

  <Card title="Code examples" href="/guides/sdk-integration">
    Authenticated calls in Node.js, Python and cURL.
  </Card>

  <Card title="MCP server" href="/mcp-server">
    Connect Claude, ChatGPT, Cursor or Codex.
  </Card>
</CardGroup>