Skip to main content
Every request to the Pear API (except public endpoints) requires authentication via an API key. This page covers how keys work, how to use them, and how to keep them secure.

​
API key format

Pear API keys follow the format mk_live_ followed by a random string: 
mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
Two ways to authenticate

You can pass your API key using either of these methods. Both are equivalent. Include your key in the Authorization header with the Bearer prefix: 
curl -X GET "http://localhost:8000/api/events" \
  -H "Authorization: Bearer mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

​
X-API-Key header

Alternatively, pass the key directly in the X-API-Key header: 
curl -X GET "http://localhost:8000/api/events" \
  -H "X-API-Key: mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
If both headers are present, the Authorization: Bearer header takes precedence.

​
Key scopes

Each API key has one or more scopes that determine what it can access:
ScopeDescription
readAccess events, markets, comparisons, search, and account data. Required for all GET endpoints.
writeCreate and manage API keys. Required for POST and DELETE operations.
Most integrations only need the read scope. Use write only for keys that manage other keys.

​
Creating API keys

Create a new key via the API: 
curl -X POST "http://localhost:8000/api/keys" \
  -H "Authorization: Bearer mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key", "scopes": ["read"]}'
The full API key is only returned once when created. Store it immediately in a secure location. You cannot retrieve the full key value later.

​
Revoking API keys

If a key is compromised or no longer needed, revoke it immediately: 
curl -X DELETE "http://localhost:8000/api/keys/key_abc123" \
  -H "Authorization: Bearer mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
Revocation is immediate and permanent. Any requests using the revoked key will return a 401 Unauthorized response.

​
Listing your keys

View all keys on your account (key values are partially masked): 
curl -X GET "http://localhost:8000/api/keys" \
  -H "Authorization: Bearer mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

[
  {
    "id": "key_abc123",
    "name": "Production Key",
    "key_preview": "mk_live_...x7f9",
    "scopes": ["read"],
    "created_at": "2024-12-01T10:00:00Z",
    "last_used_at": "2025-01-17T14:32:10Z"
  }
]

​
Error responses

StatusErrorDescription
401unauthorizedMissing or invalid API key.
403forbiddenThe key does not have the required scope for this operation.

​
Security best practices

1

Use separate keys per environment

Create dedicated keys for development, staging, and production. This limits the blast radius if a key is exposed.
2

Use the minimum required scope

Most applications only need read access. Only grant write scope to keys that need to manage other keys.
3

Store keys in environment variables

Never hardcode API keys in your source code. Use environment variables or a secrets manager.
4

Rotate keys periodically

Create a new key, update your application, then revoke the old key. Regular rotation limits the window of exposure.
5

Monitor usage

Use the usage logs endpoint to audit which keys are being used and from where.