Local prototype · simulated data

Authentication

Send a key in the Authorization header as a Bearer token. Keys never go in URLs.

Key types

Key types
Key	Where it runs	Can call	Restrictions
`sk_test_…` secret	Your server	All `/v1` endpoints	Refused when sent from a browser (`secret_key_in_browser`)
`pk_test_…` publishable	Browser	Autocomplete and selection	Only from origins on the key's allowlist (`origin_not_allowed`)
`_live_`	—	—	Planned Rejected with `live_keys_disabled`

Sending a key

HTTP header

Authorization: Bearer sk_test_PLACEHOLDER

Query-string keys are rejected on purpose, because URLs are copied into logs, analytics and browser history:

JSON

{
  "error": {
    "type": "invalid_request",
    "code": "key_in_url",
    "message": "Send API keys in the Authorization header, never in the URL.",
    "request_id": "req_0000000000000000docs",
    "doc_url": "https://docs.example.com/errors#key_in_url"
  }
}

Publishable keys and origins

A publishable key lists the exact origins (scheme, host and port, no path) that may use it, for example https://shop.example.com. Requests from any other origin fail before any data is returned:

JSON

{
  "error": {
    "type": "permission_error",
    "code": "origin_not_allowed",
    "message": "This publishable key is not allowed for this origin.",
    "request_id": "req_0000000000000000docs",
    "doc_url": "https://docs.example.com/errors#origin_not_allowed"
  }
}

Browsers send the Origin header automatically; you cannot set it from page scripts. That is what makes the allowlist meaningful for browser keys. Server-side code should use a secret key instead.

Browsers leave out Origin on same-origin GET requests. When a request carries Sec-Fetch-Site: same-origin instead, the API treats it as coming from its own origin. This only matters when the page and the API share a host, as in the local prototype; a hosted API's own domain is never on a customer's allowlist. A secret key sent with either header is refused as secret_key_in_browser.

Rotation and revocation

Create the new key, deploy it, then revoke the old one in the console. A revoked key stops working on the next request with invalid_api_key.

Storing keys

The full key is shown once, at creation. The service stores only a SHA-256 hash and a short prefix for display.
Keep secret keys in your server's secret store, never in client code or source control.