Send your key in the x-api-key header. Keys are never accepted in the query string.
curl "https://us.api.fingerly.io/api/v1/events" -H "x-api-key: $FINGERLY_SECRET_KEY"
Kinds of key
| Kind | Prefix | Used by | May call |
|---|---|---|---|
| Public | fly_pk_{region}_{environment}_ | Client SDKs, in browsers and apps | The client API |
| Secret | fly_sk_{region}_{environment}_ | Your backend | The server API, and the client API from a server |
| Proxy | fly_px_{region}_{environment}_ | Your first-party proxy | Forwards client API requests with visitor details |
| Management | fly_mk_{region}_ | Your automation and infrastructure-as-code tools | The management API |
The prefix spells out the key's region and environment, so fly_pk_us_development_… is a public key for the US region's development environment. Everything after the prefix is random. See API keys and environments.
Public keys
A public key is safe to ship in a web page or an app. What makes it safe is where it is accepted from:
- In a browser, the request's
Originmust exactly match one of the key's allowed origins, scheme and port included. A key with no allowed origins refuses every browser request. - In a native app, the mobile SDKs identify the platform instead of sending an origin.
- A public key can only submit identifications. It can never read events.
Secret keys
A secret key reads events from its own organization and environment. It is refused when the request carries an Origin header, so a secret key pasted into front-end code fails immediately rather than leaking quietly. The one exception is a development secret key used from the Try it panel on these docs, which reads only development events.
Proxy keys
A proxy lets the browser SDK reach Fingerly through your own domain. Because the request then arrives from your server, the proxy must say who the visitor really is, and a proxy key is what makes those details trusted.
| Header | Value |
|---|---|
x-api-key | The browser's public key, passed through. |
x-fingerly-proxy-key | Your proxy key. |
x-fingerly-client-ip | The visitor's IP address, from infrastructure you trust. |
x-fingerly-origin | The page's origin, checked against the public key's allowed origins. |
x-fingerly-user-agent | The visitor's user agent, up to 4,096 bytes. |
Management keys
A management key calls the management API for its organization, with the permissions of the role it was issued with, admin or developer. It belongs to no environment, is refused with an Origin header, and cannot issue or revoke management keys. Owners and admins issue them in Integration > Management keys.
Proxy key rules
The proxy key and the public key must belong to the same organization, environment and region. Forwarded visitor headers are ignored unless the request is authenticated with a proxy key or a secret key. A proxy key cannot read events.
When authentication fails
| Status | Code | Meaning |
|---|---|---|
401 | unauthorized | The key is unknown, revoked, expired, from another region, the wrong kind for the endpoint, or not allowed from where the request came. The response is the same for every cause. |
402 | billing_blocked | The key is valid, but its organization is not accepting traffic. Reading events is not affected. |
An identify request refused for an expired or revoked key, a disallowed origin or a blocked organization also sends an identification.refused webhook, which says which of those it was.