Skip to main content
When you finish, a curl request to https://api.datalyr.com/v1/workspace returns your workspace instead of 401.

​
Before you start

You must have the owner or admin role in the workspace. A member cannot generate or regenerate a key.

​
The two workspace keys

Settings → API holds exactly one key of each type. The two are not interchangeable. The /v1 handler reads the Authorization header, requires the Bearer scheme, and requires the token to start with dk_agent_. A write key fails that prefix test, so it returns 401. The write key is a send-events credential. Reading Datalyr data from your own server, or from an agent, always uses the Agent key. The Agent key reads. It never changes anything, because it resolves to datalyr:read alone and always will. To change a conversion rule or a trackable link over /v1, an owner or admin mints a named key and grants it that scope explicitly. See Agent access. POST /attribution/lookup is the one exception, and it is not a general read route. The iOS and React Native SDKs call it to resolve the install they already own, using the email that same app collected. Do not call it from your own backend with an email a user typed. Pointed at arbitrary addresses, it turns a write key into a way to read another person’s attribution history.
Keep the Agent key on your server. It reads every event, user, and revenue row in the workspace. Never put it in a browser bundle, a mobile app, or a public repository.

​
Create the key

  1. Open Settings → API.
  2. Find the Agent key card.
  3. Select generate key, or regenerate when a key already exists.
  4. Confirm in the dialog.
  5. Copy the full value from the one-time dialog.
Copy the key before you close the dialog. We store a SHA-256 hash for lookup and never show the full value again, so a lost key means regenerating, which breaks every client still holding the old one.
Regenerating invalidates the previous key at once, with no overlap window. We drop the cached lookup for the old hash in the same action.

​
Send the key

The key identifies the workspace on its own. No workspace ID or header goes in the request.

​
What a rejected request looks like

A rejected request returns HTTP 401, the header WWW-Authenticate: Bearer realm="Datalyr Read API", and this body:
Five conditions produce it: no Authorization header, a header that is not two space-separated parts, a scheme other than Bearer, a token without the dk_agent_ prefix, and a token whose hash matches no workspace. We cache both a valid and an invalid key lookup for 300 seconds, so a fresh key can take that long to take effect everywhere.

​
Verify

Run the curl command above against /v1/workspace. A 200 response with your workspace name proves the key works.

​
When it doesn’t work

​
Next