Home
Back to docs

API Keys

A key lets an outside program work with the system without a person signing in; it is shown once, limited to the permissions you tick, and is a powerful secret to be given as little as possible.

Keys that let outside programs work with this system without a user signing in.

A key is shown once

The full key (ak_ followed by 64 characters) is displayed once, when it is created. Afterwards only its first 10 characters are visible; the system keeps a hash, not the key. If it was not copied at that moment there is nothing to recover: revoke it and issue a new one.

You choose its permissions

Every key is created with a list of permissions (called scopes) and at least one is required. A scope is either an exact permission such as crm.leads.read or a whole plugin such as crm.*. * (everything) is refused, and a permission that does not exist is refused at creation.

You can give a key only permissions you hold yourself. Platform-operation permissions can be given only by a superadmin.

A key is limited to its scopes wherever the system checks permissions, but a key is still a bearer secret: anyone who holds it acts with those permissions, from anywhere. A key with broad scopes (user or role management, or the right to create more keys) is a broad delegation. Grant the minimum, give each integration its own key, and set an expiry.

A key acts as itself, not as a person

Calls made with a key have no user behind them. Actions that need "the calling user" (for example "my tasks") are refused for a key with a 403 error saying which wider permission would be needed.

Keys belong to the installation

A valid key works on every hostname this install answers on; keys are not tied to a site or an address, and there is no way to restrict one to an IP.

Revoking is immediate and final

A revoked key stops working at once and cannot be reactivated. It stays in the list as Revoked. Delete removes the row permanently. A key also stops working if the person who created it is deactivated, and deleting a person revokes the keys they created.

Expiry

A key can be given an expiry date when it is created, and an expired key is refused exactly like a revoked one. An expiry cannot be changed later. The system has a "default lifetime" setting for new keys without a date, but there is no page to set it, so in practice set the date yourself.

Permissions and plan

Seeing the page needs the API Keys read or manage permission; the Admin role has both and the Editor role has neither. Creating, revoking and deleting are plan features, so a plan without them shows the list with the buttons locked.

How do I…