Authentication

Send your keyCopy Anchor Link

Send your API key in the X-API-Key header on every call. Any tool that lets you add a custom header can send it.

curl -X POST "https://realpng.com/api/v1/audit" \
  -H "X-API-Key: $REALPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://realpng.com/run-portrait.jpg"
  }'

Every key starts with rp_live_. The MCP server takes the same key.

Use the Authorization headerCopy Anchor Link

If your client expects the Authorization header, send the same key with the Bearer scheme.

curl -X POST "https://realpng.com/api/v1/audit" \
  -H "Authorization: Bearer $REALPNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://realpng.com/run-portrait.jpg"
}'

Bearer is not case sensitive. If a call sends both headers, realpng reads X-API-Key and ignores Authorization.

Keep keys on your serverCopy Anchor Link

Every key is live. There are no test keys, so every check and optimization spends credits from your plan.

The API sends no CORS headers, so a web page on another site cannot call it from the browser. A key in browser code is also visible to anyone who opens the page. Call realpng from your server and keep the key in an environment variable such as REALPNG_API_KEY.

Create a keyCopy Anchor Link

1. Sign in and open API keys.
2. Choose Create key.
3. Type a short name, for example n8n pipeline, and choose Create key.

The name is required and must be unique on your account. Names that differ only in case or in spaces at either end count as the same name.

The new key appears once. Open Callback signing secret below it to reveal the key's signing secret. realpng stores only a hash of the key, so nobody can recover it, including us. If you lose a key, revoke it and create a new one.

The keys table lists each key's name, the start of the key, when it was created and when a call last used it.

Keys per planCopy Anchor Link

Every key on an account spends that account's credits. All its keys share one rate limit and one cap on jobs at once, as Rate limits explains. Any key on the account can read an optimization that another key started.

How many keys you can hold depends on your plan. Free has none. Plans lists the count for each paid plan. At the limit, you cannot create a key until you revoke one or upgrade.

After a downgrade to a smaller paid plan, keys above the new limit keep working. You cannot create keys until you have fewer than the plan allows.

Signing secretCopy Anchor Link

Each key comes with its own signing secret, which starts with whsec_. It is shown once, under Callback signing secret when you create the key.

The secret signs the webhooks for optimizations the key starts with callback_url. Verify the signature shows how to check one.

If you lose the signing secret, create a new key, which comes with a new secret. A secret cannot be replaced on its own.

Revoke a keyCopy Anchor Link

In the keys table at /account#keys, choose Revoke on the key, then Revoke again to confirm. It takes effect at once, and the next call with that key gets 401. The key's name and its place in your plan's limit are free again.

To rotate a key, create a new one, deploy it everywhere the old key runs, then revoke the old key. At your plan's key limit, revoke a key first to make room for the new one. Webhooks for optimizations already running are still signed with the old key's secret.

When a key is refusedCopy Anchor Link

A call without a valid key gets 401 invalid_key. That covers a missing key, a malformed key and a revoked key.

{
  "code": "invalid_key",
  "message": "Send a valid key as X-API-Key or Authorization: Bearer."
}

A valid key can still be refused with 402:

• plan_required means the account's plan has no API access. Free is the only plan without it. Keys created before a downgrade to Free stay listed, but answer 402 until you upgrade.
• payment_failed means the last payment failed. Existing keys answer 402, and you cannot create keys, until you update your card at /account#billing.

A canceled plan keeps API access until the end of the period you paid for. After that the account is on Free and its keys answer plan_required.

Errors lists every code with its fix.

Next stepsCopy Anchor Link