Create, rotate and revoke Leadnote API keys

An API key lets another system call the Leadnote public API on behalf of your organisation. Create one key per system, give it only the scopes it needs, and revoke it the moment you no longer trust it. Only Account Owners and Managers can create, rotate and revoke keys.

Create a key

1. Open Settings and choose API Integration, or find the Other Enterprise Systems (API) card on the integrations hub. The page is titled API and webhooks. Open the API keys tab.
2. Choose Create API key.
3. Enter a Name, up to 80 characters. It is shown only to you, so use something like "Website backend".
4. Choose one or more Scopes (see the table below). You must pick at least one.
5. Choose an Expiry: Never expires, 30 days, 90 days, 180 days or 1 year. An expired key stops working on its own.
6. Choose Create key.
7. Copy the key from the Your new API key window and confirm that you stored it. It is not shown again.

A key looks like lnk_ab12cd34_ followed by 32 more characters. Never paste a real key into a public place such as a shared document or a code repository.

Scopes

Scopes add up. A key with leads:write cannot read leads unless it also has leads:read. A call that needs a scope the key lacks is refused.

Use a key

Send the key in the x-api-key header, or as a bearer token:

x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

Each key can make 60 requests a minute on the public API. Zapier endpoints allow 240 a minute. When you go over, Leadnote answers with a Retry-After header that says how long to wait. The API reference tab lists the calls a key can make. See the public API for developers.

The key table shows each key's name, the first characters of the key, its scopes, its Status (Active, Expiring, Expired or Revoked), when it was Last used and when it Expires.

A key stops working immediately if your organisation is suspended, and if the user who created it is deactivated.

Rotate a key without downtime

Rotating replaces a key while the old one keeps working for a short time. Use it before a key expires, when a team member who knew the key leaves, or when you want a routine change.

1. In the key table, choose Rotate on the key.
2. Set the Grace period (hours), from 0 to 168. The default is 24. At 0 the old key stops at once.
3. Choose Rotate key.
4. Copy the new key. It has the same name, scopes and expiry window as the old one.
5. Update your systems to use the new key within the grace period.

While the grace period runs, the old key shows as Expiring and the rows show which key replaced which. After it ends, the old key stops working.

Revoke or delete a key

• Revoke stops a key right away. Every system using it is refused from that moment. The key stays in the table as Revoked and cannot be restored.
• Delete removes a revoked key from the table for good, together with its rotation links and any Zapier subscriptions that were tied to it. Only revoked keys can be deleted.

Revoking is what makes a key stop working. Deleting only tidies the list.

Creating, rotating and revoking a key are recorded in the audit log. See the audit log.

Good habits

• Use one key per system, so you can revoke one without breaking the others.
• Give each key the fewest scopes that work.
• Set an expiry for keys that contractors or agencies use.
• Keep keys out of front-end code. A key in browser code is visible to everyone. For forms on a public website, use the hosted form or an embed instead.
• Rotate a key at once if it may have leaked.

If a call is refused

A missing, revoked or expired key is refused as not authenticated, and a key without the right scope is refused as not allowed. The error format is described in the public API for developers.