# API keys

Source: https://holofolder.com/app/docs/api-keys

Your first request, in a few minutes.

Personal API keys connect your scripts and integrations to Holo Folder. Create a key, keep it on your server, and send it with each request.

[
Open the API explorer
](https://holofolder.com/app/docs/markdown/reference/catalog/list-cards)
[
Connect an AI assistant
](https://holofolder.com/app/docs/markdown/mcp)

**Using Claude, ChatGPT, Cursor or Codex?**

Use the [AI setup guides](https://holofolder.com/app/docs/markdown/mcp) to connect through MCP with your Holo Folder login. You won't need to create or
paste an API key.

## Create a key

Create a key here using your signed-in account. You can also manage the same keys in **Settings → Account → Developer access** in the app.

[Create or manage an API key in the interactive guide](https://holofolder.com/app/docs/api-keys#create-a-key)

1. Sign in above if you haven't already.
2. Give the key a name you'll recognise, such as “Collection export”.
3. Choose its permissions and expiry. Start with read access.
4. Copy the full key and save it somewhere secure. It's shown only once.

A current Premium subscription or lifetime licence is required. Signup trials do not include developer access.

## Authentication

Send the full key in the `Authorization` header with the `Bearer` prefix:

```http title="Request header"
Authorization: Bearer hf_YOUR_KEY_ID.YOUR_SECRET
```

Keep the key in a server environment variable. Never put it in a URL, browser bundle or public repository. The REST API uses personal API keys; browser cookies and MCP OAuth tokens cannot replace them.

## Make your first request

This request returns up to ten cards. Replace the placeholder with your key:

```sh title="Terminal"
export HOLOFOLDER_API_KEY='hf_YOUR_KEY_ID.YOUR_SECRET'

curl --fail-with-body \
  -H "Authorization: Bearer $HOLOFOLDER_API_KEY" \
  'https://app.holofolder.com/app/api/v1/cards?limit=10'
```

Use the returned `nextCursor` with the same filters to continue. See [pagination](https://holofolder.com/app/docs/markdown/contracts#pagination) for the full convention.

Prefer to try it in your browser? Open [Search cards](https://holofolder.com/app/docs/markdown/reference/catalog/list-cards), select **Try in Playground**, enter your key, and send a request. The explorer also generates code examples from your inputs.

## Choose permissions

Read access is the default. Select writes explicitly only when your integration needs them. Each endpoint in the [API explorer](https://holofolder.com/app/docs/markdown/reference) lists the permissions it requires.

| Permission                                            | What it allows                                 |
| ----------------------------------------------------- | ---------------------------------------------- |
| `catalog:read`                                        | Browse cards, sets and Pokémon                 |
| `binders:read`, `collection:read`                     | Read your binders, collection and wanted cards |
| `prices:read`                                         | Read available price evidence                  |
| `settings:read`                                       | Read settings and account identity             |
| `binders:write`, `collection:write`, `settings:write` | Change the corresponding account data          |
| `prices:refresh`                                      | Request provider refreshes within their limits |
| `sharing:manage`, `partners:manage`                   | Manage sharing and partner access              |

A valid key still needs paid access and the right permissions. Partner access follows current membership. Revocation is checked on every request.

## Expiry, rotation & revocation

Keys expire after **30, 90 or 365 days**, with **90 days** as the default. Each account can have up to **ten active keys**.

Revoke a key at any time in developer settings. Rotation creates a new key; existing secrets cannot be recovered. Update your integration to use the replacement, then revoke the old one.