API Key Management

Create Horizon API keys, choose what each key may do or give it full access, choose which boards it can reach, and rotate, revoke or delete keys from Settings.

API keys let a program call the Horizon API on behalf of your organization. You create and manage them on the API Keys tab of Settings.

Before you start

You need the owner or admin role. Anyone else who opens the tab sees “You don’t have permission” instead of the key list.

Create a key

1. In the sidebar, open Settings, then select the API Keys tab.
2. Select Create API Key.
3. Enter a Name. The key list does not show who created a key, so give it a name that says who or what uses it.
4. Under Module permissions, choose what the key may do, or select Full access (includes future features). See Module permissions and Full access.
5. Under Board access, choose which boards it can reach. See Board access.
6. Select Create Key.
7. The API Key Created dialog shows the key. Select Copy, store the key somewhere safe, then select Done.

Module permissions

The matrix has one row per module, showing how many of its features the key can use. Expand a module to set permissions feature by feature, and expand a feature to set them record by record. The checkboxes on the module’s own row set the same action on every feature in it that offers that action. The search box narrows the features shown inside an expanded module.

Nothing is granted by default: a key saved with no boxes ticked, and without full access, has no access to your organization’s data.

A greyed-out, locked box marks an action that no API key can hold on that feature, whatever else the key is given. Point at it to see why, for example API keys can only read this. A module’s own row skips those features and says how many it skipped, for example Write (10 read-only) on Finance. See Actions no key can hold.

Full access

Full access (includes future features), at the top of Module permissions, gives the key every feature in every module, including features Horizon adds later. While it is on, every box shows ticked for each action a key can hold there, and you cannot change individual boxes. The key list shows the key’s permissions as Full access (includes future features).

Full access still has the limits every key has:

• It cannot hold an action no key can hold. See Actions no key can hold.
• It does not open the parts of Horizon that are closed to keys. See Parts of Horizon a key cannot reach.
• It acts as the person who created it, with their role and legal-entity access. See Use a key.

A key has either full access or the boxes you tick, never both.

Switching full access off:

• Before you save, it puts back the boxes you had ticked when you switched it on.
• On a key saved with full access, it starts from exactly what the key can do today, so saving straight away changes nothing the key can do now. It ticks the features, and a feature’s boxes cover the records in it, so a record’s own boxes can show unticked. Untick anything the key should not have, then select Save. From then on the key covers only what is ticked, so features Horizon adds later are not included.

Actions no key can hold

Some features limit what any API key can do there, whatever you tick and even with full access. A request for one of these actions is refused with 403 and a message saying no key can be granted it. On the key screen, the box for it is locked.

Read only. A key can read these, and cannot create, change or delete them:

Under Non-Profit, only the feature’s own row and the records listed are read-only. The other records in that feature accept Write and Delete, and Execute where they have workflow actions.

Read and write, but not delete: Data Migration Pipeline (Workspace), and Multi-Entity Separation and Operator Chat (System & Platform).

Write only: Primary Legal Entity, Report Builder (conversational) and Report Mockup Ingestion (System & Platform).

To import finance records with a key, use the migration hub rather than Finance Migration: give the key Read and Write on Data Migration Pipeline under Workspace, and start with POST /api/v2/migration/areas/finance/programs.

Parts of Horizon a key cannot reach

Some parts of Horizon are for signed-in people only. No box and no full access opens them:

• Settings, including the API Keys tab, so a key cannot create, list or manage keys, itself included. The only settings a key can reach are the two in Organization setup with a key.
• Inviting people to your organization, renaming it, and leaving it.
• Billing, apart from reading the wallet: buying credits, auto-refill and subscriptions.
• The fiscal-year setup in Finance.
• Connections, agents, apps, skills, onboarding, the dashboard and notifications.

A key can still list, add and remove organization members, through /api/v2/agent/users with the Org Members permission under System & Platform. It adds only people who already have a Horizon sign-in; it does not send invitations. See Organization members.

A request to a part of Horizon that is closed to keys is refused with 403 PERMISSION_DENIED and the message API keys cannot access this endpoint. Buying credits and changing auto-refill are refused as actions no key can hold instead, because they sit under Wallet Balance, which is read only.

Organization setup with a key

Four features under System & Platform let a key help set up an organization. Only a key that has been given them, or a key with full access, can use them: no other permission includes them.

• Primary Legal Entity sets your organization’s primary legal entity. Send { "legalEntityId": "<id>" }, the id of an active legal entity in your organization. It answers { "data": { "primaryLegalEntityId": "<id>" } }, 404 ENTITY_NOT_FOUND for an entity not in your organization, and 409 ENTITY_NOT_ACTIVE for one that is not active.
• Wallet Balance returns your organization’s wallet, including its balance, which is a string, and its auto-refill and subscription settings. Buying credits and changing auto-refill stay closed to keys. See Wallets.
• Multi-Entity Separation is the Multi-entity separation setting on the General tab of Settings. PATCH takes { "mode": "standard" }, where mode is off, standard, strict, or null for Inherit (platform default). GET returns multiEntityMode, the stored setting, and effectiveMode, the mode that applies now.
• Operator Chat is the Operator Chat setting on the General tab of Settings. PATCH takes { "enabled": true } or { "enabled": false }. GET returns operatorEnabled.

Each change is recorded in your organization’s audit trail as made through the API. For the three owner-or-admin features, the key’s creator must still hold one of those roles when the request is made; otherwise the request is refused with 403 INSUFFICIENT_ROLE.

Board access

The dialog recommends the third option for agent and bot keys.

A request for a board the key cannot reach is answered as if the board did not exist.

Use a key

Send the key as a bearer token to https://api.horizonplatform.ai/api/v2:

Authorization: Bearer hzn_your_key_here

A key acts as the person who created it. Anything that depends on a role checks that person’s current role, and in an organization that separates data by legal entity, the key sees and changes only what that person can. A key works only while that person is an active member of your organization:

• If they are removed from the organization, or leave it, requests with the key get 401 KEY_OWNER_NOT_FOUND.
• If they are deactivated, requests with the key get 403 MEMBER_DEACTIVATED.

Neither revokes the key. It stays active in the list, and it works again from its next request if the person is reactivated or rejoins the organization. To stop a key for good, revoke or delete it. When you deactivate someone, the confirmation lists their active keys; see Deactivating a User.

A key has no rate-limit setting of its own, and limits do not vary by plan. Each key can make 1,000 requests per 60 seconds to the App API’s /api/v2/agent/* routes and, counted separately, 100 per 60 seconds to the other routes it can reach. A request over a limit is answered with 429. See Rate limits.

When a request is refused

For every response shape, see Which routes an API key can reach in the App API reference, which also lists the routes a key can call, what each permission and board-access option controls there, and every endpoint’s request and response.

The key list

Each key in the list shows:

• Name — the name you gave it.
• Key — the start of the key, so you can match it to the one you stored.
• Permissions — Full access (includes future features); or each module the key holds permissions in, with a count; or No access.
• Boards — All boards, Owner’s boards, or the number of selected boards.
• Status — active or revoked.
• Created — the date the key was created.
• Last Used — the date the key last authenticated a request, or Never.
• Expires — Never for any key created here, because the dashboard does not set an expiry.

An active key has Edit, Rotate, Revoke and Delete. A revoked key has only Delete.

Edit a key

Select Edit to change the key’s Name, Module permissions, including Full access, or Board access, then select Save. The key itself does not change, and the new permissions apply from its next request.

If the key holds a permission Horizon has since retired, the dialog lists it as removed; saving drops it.

Rotate a key

Select Rotate to replace the key with a new one. The new key appears once, in the same API Key Created dialog as at creation. The name, permissions and board access stay as they were.

Revoke a key

Select Revoke to stop a key working. It takes effect immediately and does not ask you to confirm.

A revoked key stays in the list with the status revoked. It cannot be edited, rotated or turned back on; create a new key if you need one.

Delete a key

Select Delete, then Delete again in the Delete API key dialog. The key is removed from the list permanently. You can delete an active key or a revoked one; deleting an active key also stops it working.