Authentication

API keys, the Bearer header, test keys, rotation, and using the playground.

Every endpoint except GET /v1/health and GET /v1/openapi.json needs an API key, sent as a Bearer token in the Authorization header:

curl "https://api.pinakelai.com/v1/usage" \
  -H "Authorization: Bearer pk_live_..."

The scheme name is case-insensitive (Bearer, bearer). If a request carries both Authorization and the old X-API-Key header, the Authorization header is used.

​

Keys

A key is pk_live_ or pk_test_ followed by 43 URL-safe characters.

Key	Data	Limits	Billed
pk_live_…	All registers your agreement covers	Your agreement’s per-minute rate limit and monthly quota	Yes
pk_test_…	The same data as a live key	Lower rate limits	No

Use test keys for development, CI and the playground on this site, and live keys only in production services.

Pinakel issues keys when your agreement is set up. A key is shown once, when it is issued; we store only a hash of it, so we cannot show it to you again. If you lose a key, rotate it.

​

Rotating a key

Rotate a key yourself in the customer portal at portal.pinakelai.com: open API keys, choose Rotate…, and copy the new key, which is shown once. The old key stops working within about a minute, so deploy the new key first if you can schedule the rotation. Rotate immediately if a key may have leaked, for example into a log, a ticket or a repository.

Revocation works the same way: Pinakel revokes keys on request or when an agreement ends, and requests with the key fail within about a minute.

​

When authentication fails

Authentication errors are problem details. Every 401 response carries a WWW-Authenticate header (RFC 6750).

Situation	Status and type	WWW-Authenticate
No credential	401 unauthenticated	Bearer realm="api.pinakelai.com"
Only an X-API-Key header (the detail explains the fix)	401 unauthenticated	Bearer realm="api.pinakelai.com"
A key in the query string (api_key, access_token, key)	401 unauthenticated	Bearer realm="api.pinakelai.com"
An unknown or malformed key	401 unauthenticated	Bearer realm="api.pinakelai.com", error="invalid_token"
A revoked key	401 key-revoked	Bearer realm="api.pinakelai.com", error="invalid_token"
A valid key that does not include the Data API	403 product-not-enabled	Bearer realm="api.pinakelai.com", error="insufficient_scope", scope="data:read"

A key in the query string is rejected even when it is valid, and it is removed from our request logs. Query strings end up in proxy logs, browser history and analytics tools, so never send credentials that way.

After 20 lookups of unknown keys from one IP address within a minute, that address receives 401 with a Retry-After header for 5 minutes, including requests with a valid key that has not been used successfully within the last minute. A misconfigured deployment that retries with a wrong key can lock out the rest of your traffic from the same egress address. Do not retry a 401 automatically.

Authentication failures (401 and 403) are not counted toward your usage.

​

Using the playground on this site

Each page in the API reference has a Try it button. The playground sends requests from your browser straight to api.pinakelai.com; they do not pass through the documentation host. The API accepts these browser requests only from https://docs.pinakelai.com.

Use a pk_test_ key in the playground. Your browser may keep the key you enter, so clear it on a shared machine.

​

Keep keys on the server

A key identifies your organisation and carries your quota. Call the API from your own servers, not from browser or mobile code that end users can inspect. Security covers storage, separate keys per environment, and incident response.

Bearer tokens that do not start with pk_ are reserved for OAuth 2.0 access tokens with the data:read scope, planned for a later release. Today, such tokens get 401 unauthenticated.