API keys

The short answer

A live API key can be created when three things are true: your organization holds the API add-on, which is sold with an annual plan; an admin has enabled API access for you (Members → Manage); and you hold a seat. Each person may hold two active live keys. Keys are created and revoked under Your account → API keys. The full key is shown once, when it is created; Data Tactical Group stores only a hash, so a lost key is revoked and replaced, not recovered.

Creating a key

Open Your account → API keys and create a key. Copy it at once: afterwards the list shows only its first characters. If you cannot create one, one of the three conditions above is not met; an owner or admin can tell you which. The free account and the county trial do not include live keys.

A sandbox for trying the API with fabricated data is available. Any verified account can mint a sandbox key, with no plan; sandbox keys are counted separately from live keys.

A key reads. It reads data and the account’s details, and changes nothing on the account or the organization: a change sent with a key is refused (HTTP 403, code session_required), and is made in the app instead.

Limits

Every request made with a key counts against two rate limits: 120 requests a minute per key and 300 a minute per organization, the same on every plan. The data a key returns is metered in points against the organization’s monthly allowance; see points and usage. The rate limits page in the API section has the response a client sees when it reaches one.

Revoking a key

The person who holds a key can revoke it, and so can the organization’s owner or an admin. Revoking is immediate and cannot be undone; the key’s row stays in the list as a record. When an owner or admin revokes someone else’s key, the holder is told by email and the owners and admins see a notice. A revoked key that is still used is refused, saying when and why it was revoked.

What happens to keys when things change

Payment is past due. Keys are kept but refused until a payment succeeds, and new keys cannot be created. They work again as soon as the balance is settled.
The API add-on ends. Every live key in the organization is revoked.
A member leaves or is removed, or closes their account. Their keys in that organization are revoked.
An admin turns off a member’s API access. That member’s live keys are revoked.
A member loses their seat. Their live keys are revoked, because an unseated member has no API access.
The organization is suspended or closed. Keys stop working.
A password is reset. Keys are kept. The confirmation email lists the keys you hold, so you can revoke any that is not yours.

Making a first request with a key is on the API quickstart and authentication pages, and the key endpoints themselves are in the keys and usage reference. Roles are on organizations and members.