Skip to main content
When you finish, you hold the one key your integration needs, stored in a secret manager and out of your client code.

​
Before you start

You must have the owner or admin role. A member sees the cards without the buttons.

​
The two keys

Settings → API holds exactly one key of each type. Which one you need depends on whether you’re reading data or writing events. Neither key belongs in browser code. Browser and mobile installs carry the public workspace ID from Settings → General instead, which is safe to ship. The write key sends events. It reads nothing, so any server-side or agent read of your data uses the Agent key instead. The mobile SDKs also send the write key to POST /attribution/lookup, to resolve the install they already own. Do not call that route from your own backend with an email a user typed. See Authentication. A key authorizes exactly one workspace. If a response looks like someone else’s data, you’re holding another workspace’s key.

​
Named keys carry write scopes

The Agent key reads and never writes. It resolves to datalyr:read alone and always will, so no key already in circulation gained the power to change anything. To let your own code or an agent change a conversion rule or a trackable link over /v1, an owner or admin creates a named key in the dashboard and grants each scope explicitly: datalyr:write:rules, datalyr:write:links, or datalyr:propose:scripts. A request without the matching scope returns 403 and names the scope it wanted. See Agent access.

​
Generate a key

  1. Open Settings → API.
  2. Find the card for the key you need.
  3. Select generate key.
  4. Confirm in the dialog.
  5. Copy the full value from the one-time dialog.
  6. Store it in an environment variable or a secret manager.
Copy the value before you close the dialog. We store a hash for lookup and never show the full value again, so the card afterwards shows only a masked preview such as dk_agent_••••••••a1b2.

​
Rotate a key

Rotation has no overlap window. The old key stops working the moment you confirm, so every service still holding it fails before you finish deploying. Rotate when you can update every consumer in one go.
  1. List every service that holds the current key.
  2. Select regenerate on the card.
  3. Confirm in the dialog.
  4. Copy the new value from the one-time dialog.
  5. Update the secret in every environment.
  6. Redeploy or restart those services.
We drop the cached lookup for the old Agent key in the same action, so the revoked key fails at once rather than lingering.

​
Verify

Run one authenticated request with the new key:
A 200 response naming your workspace proves the key works. See Authentication for the full 401 body.

​
If a key leaks

  1. Select regenerate on the affected card immediately.
  2. Update every consumer with the new value.
  3. Review your own service logs for requests you did not make.
Never paste a full key into a support ticket. Send the prefix and the last four characters, which is enough for us to identify it.

​
When it doesn’t work

​
Next