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

# API keys

> Create, use, protect, and rotate the keys that authenticate the Paperjoy API and Zapier.

Every API request needs an API key in the `Authorization` header. Zapier uses the same keys. The [MCP server](https://docs.paperjoy.co/en/integrations/mcp.md) does not; it signs in through your browser instead.

```bash theme={null}
curl https://paperjoy.co/api/user \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json"
```

A working key returns your account and `available_credit_balance`.

## Create a key

**1. Pick the mode**

Keys belong to the mode that is active when you create them. Turn on [test mode](https://docs.paperjoy.co/en/getting-started/test-mode.md) for a `pj_test_` key, or leave it off for a `pj_live_` key.

**2. Open the API keys page**

Go to [**Ustawienia → Klucze API**](https://paperjoy.co/settings/api-tokens) (Settings → API keys). You can also reach it from the account menu.

**3. Name and create the key**

Use a name that tells you where the key lives, such as `shop-backend` or `zapier-crm`, and click **Utwórz klucz** (Create key).

**4. Copy it right away**

The full key is shown only once. Paste it into your secret manager or environment variables before you leave the page.

![The API keys page right after creating a key, with the one-time key display and the list of issued keys.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/api-token-created.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=a997ac0e3d3f99ffd7eb6d407a6d48b2)

## Test and live keys

| Prefix | Mode | What `POST /api/postcards` does |
| - | - | - |
| `pj_test_` | Test | Creates a free test postcard that is never mailed. |
| `pj_live_` | Live | Places a real order and uses one credit. |

The prefix helps you and secret scanners recognize a key. The mode itself is stored with the key and can't change.

## Abilities

Keys created in the app can do everything below.

| Ability | Allows |
| - | - |
| `user:read` | `GET /api/user` |
| `postcards:read` | `GET /api/postcards`, `GET /api/postcards/{id}` |
| `postcards:write` | `POST /api/postcards`, `POST /api/postcards/preview` |
| `signatures:read` | `GET /api/signatures`, `GET /api/signatures/{id}` |
| `signatures:write` | `DELETE /api/signatures/{id}` |

## Limits

| Limit | Value |
| - | - |
| Keys per user | 20, counting both modes |
| Lifetime | 1 year from creation |
| Name | 3–80 letters, numbers, spaces, `.`, `_`, or `-` |

## Rotate or revoke a key

To revoke a key, open **Więcej** (More) next to it and choose **Unieważnij klucz** (Revoke key). It stops working immediately. The page only lists keys for the current mode, so switch modes to manage the others.

To rotate without downtime:

1. Create the new key.
2. Deploy it to your integration.
3. Confirm requests succeed.
4. Revoke the old key.

Plan a rotation before the one-year expiry date shown next to each key.

## Keep keys secret

* Keep keys on your server, in a secret manager or environment variables.
* Never put a key in browser JavaScript, a mobile app, or a public repository.
* Use a separate key per integration so you can revoke one without breaking the others.
* Revoke a key immediately if it may have leaked.

> [!WARNING]
>
> Anyone with a `pj_live_` key can place real orders on your account. Treat it like a password.


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