Authentication and keys

Every request to the Horizon API is authenticated with an API key. This page covers the life of a key, from creating it to revoking it, and what it can and cannot do.

Creating a key

Keys are created in the app, in Settings, under API keys & webhooks. Only the account owner can create, see or revoke keys; team members cannot, whatever their role. The steps are on API keys.

Name each key after what will use it, for example “ERP order sync” or “Warehouse stock export”. You cannot read a key’s value later, so the name is how you will know where it went.

You cannot create a key with another key or through the API at all. Key management needs a signed-in person.

Copy it once

Right after you create a key, the app lets you copy the full key, for a short time and only on that page. After that, Horizon shows only a masked preview, enough to tell keys apart and useless as a credential.

Horizon does not keep a readable copy. It stores a one-way hash of the key, so nobody at Horizon can look a key up for you. If you lose one, create a new key, move your integration to it and revoke the old one.

Treat the key as one opaque string. Do not shorten, re-case or split it.

Sending it

Send the key on every request, in either header:

Authorization: Api-Key <your key>
X-API-Key: <your key>

curl https://api.horizonlogistics.eu/api/returns/requests/ \
  -H "X-API-Key: $HORIZON_API_KEY"

A header that says Api-Key but is malformed, or a key that is unknown or revoked, is refused outright. It never falls back to an anonymous request. See Errors for the codes.

What a key can do

A key authenticates as the account owner, and it works only on the API documented in this section, plus reading which account the key belongs to. That API reads your data, and besides that it can:

• create an order;
• ask Horizon to refresh an order’s tracking;
• download an order’s shipping documents, or several orders’ labels, as one PDF.

There are no scopes: two keys on the same account have exactly the same power, over the whole account.

What a key cannot do

Nothing that costs money or changes what your customers or your stores see can be done with a key. That holds even inside the areas the API covers. A request made with a key for anything outside the documented API is answered 403 with "code": "api_key_forbidden", and nothing is done. That includes:

• buying a label, for an order or for a return, one at a time or in bulk, and any carrier command such as booking or cancelling a pickup;
• changing or deleting an order, or uploading orders from a file (an upload runs your automation rules, which can buy labels);
• deciding or re-checking an address, which can release an order’s held automatic label;
• creating a return or moving one through its lifecycle (approve, reject, cancel, in transit, received, complete): these write to your store and email your customer, and completing one can refund in Shopify;
• refunding in Shopify, issuing store credit or creating an exchange order from a return;
• recording tracking events, which email your customers and start their return window;
• replacing or revoking a shipment’s public tracking link;
• billing: plans, payments, top-ups, wallet holds and billing details;
• settings: account settings, webhooks, notifications, branding and automation;
• connections: linking or changing stores, carrier accounts, ERP systems and printers;
• API keys, team members, the password, sign-in email, two-step verification and signed-in sessions;
• exporting all of the account’s personal data, and deleting the account;
• the AI analyst.

Do these in the app, signed in as yourself. If your integration needs something that is not in the reference, contact support rather than working around it: an endpoint becomes part of the API only when it is documented here.

Rotating a key

There is no “rotate” action; you rotate by overlap:

1. Create a new key with a name that says what it replaces.
2. Put the new key into your integration and deploy it.
3. Check that the integration works on the new key. Each key’s card in the app shows the date it was last used; when the old key’s date stops changing, nothing is using it any more.
4. Revoke the old key.

Rotate on a schedule that suits your security policy, and immediately when someone who had access to a key leaves.

Revoking a key

Revoke a key from its card in the app. It stops working on the next request; there is no grace period and no undo. Anything still using it starts receiving authentication errors at once, so know what uses a key before you revoke it.

Revoke a key whenever:

• you cannot say what is using it;
• the system or person that used it is gone;
• it may have been exposed, for example committed to a repository, pasted into a ticket or logged.

Keeping keys safe

• Store keys like passwords. Use your platform’s secret store or environment configuration, never source code, spreadsheets or chat.
• Keep keys on servers. Never put a key in a web page, a mobile app or anything else that runs on a customer’s device: anyone can read it there.
• One key per integration. If one system is compromised, you revoke one key and nothing else stops.
• Do not log it. Make sure your HTTP client and proxies do not write request headers to logs.
• Review the list. Check the API keys card from time to time and revoke anything you do not recognise or that has not been used in a long while.