Organization API keys
Every request carries an organization API key as a Bearer token.
A key belongs to your organization, not to a person’s browser session. It keeps working when the person who made it signs out. It stops working when it expires, when it is revoked or deleted, or when its creator stops being an active owner or admin of the organization.
Who can create keys
Organization owners and admins manage keys in the Parlay web app under Settings → API Keys, signed in with their normal Parlay account. Other members don’t see the page. Key management needs a signed-in browser session on purpose: an API key can never create, rename, roll, revoke or delete keys, so a leaked key cannot make more keys. When you create a key you choose:
Keys that include
transcripts:read ask you to accept the transcript terms first, because transcripts contain what customers said. Your acceptance (who, when and which version of the terms) is saved with the key.
Rolling a key
Roll creates a replacement key with the same name and permissions. The old key keeps working for 24 hours (or until it would have expired, if sooner), so you can deploy the new one without downtime.1
Roll the key in Settings
Copy the new key. It is shown once.
2
Deploy it
Update your secret manager and restart or reload your service.
3
Confirm
Call
GET /me with the new key. The old key stops on its own within 24 hours.Revoking a key
Revoke stops a key on its next request. Use it the moment you suspect a key was exposed, then create a new one. Requests with a revoked key return401 unauthorized.
Renaming and deleting a key
Rename changes only the label you see in Settings. The key itself doesn’t change, so nothing needs redeploying. Delete stops the key on its next request, like revoke, and also removes it from your key list. Use it to clear out keys you no longer need, including old revoked or expired ones. Deleted keys still appear in your audit trail (GET /audit-events), so you can see what they did.
Keeping keys safe
- Server side only. Never put a key in a browser, a mobile app or a public repository.
- One key per system. A warehouse sync and a CRM integration should each have their own key, so you can revoke one without breaking the other.
- Least privilege. A sync that only needs calls should not hold
contacts:reador write permissions. - Watch usage.
GET /keys/{key_id}/usageandGET /audit-eventsshow what each key did.