API keys belong to a person

Getting a key

Keys are created on the account page of the app, not here. An organization must hold the API add-on, which is sold with annual plans on every paid tier, and an admin must have enabled API access for you. Each person may hold two active live keys, which begin dtg_live_; sandbox keys are counted separately. The key is shown once, at creation; afterwards only its prefix is visible. There is no signup, login or key management on this site; the endpoints the app uses for keys are in the keys and usage reference.

Sending the key

Send it in the Authorization header as a bearer token on every request. A key is bound to the person and organization it was created in, so every request is attributed to a named member and metered against that organization. Never put a key in a URL, a client-side script, or a shared document; a key is a credential for one human. A key reads: it reads data and the account’s details, and changes nothing on the account or the organization. A change made with a key is refused with a 403 and the code session_required; make it in the app.

Rotation and revocation

To rotate without downtime, create a second key, move your integration to it, then revoke the first. A revoked key answers 401 key_revoked on its next use, saying when and why it was revoked; a key that never existed answers 401 unauthenticated. Removing a member from the organization revokes their keys immediately. Removing the API add-on revokes the organization’s live keys, and taking away a member’s seat or their API access revokes theirs. Live keys stop working while a subscription is past due, with a 403 plan_required naming past_due, and work again when it is settled.