Skip to main content
An API key lets a program call the Omnilinker API without a person signing in: a reporting tool, a web shop or middleware that moves orders. Open API keys in the main menu to create and manage keys. The page is in Administration > Settings, under Integrations > API keys, at /settings/integrations/api-keys; the menu item is a shortcut to it. A key acts as the person who created it, limited to the access chosen for it. It can never do more than its owner can:
  • A key can use a permission only if the key was given it and its owner still holds it. If you lose a permission, your keys lose it too.
  • A key stops working when its owner’s account is deactivated or locked out.
  • Some permissions are never available to a key, whatever its owner holds; see What no key can do.
How a program sends the key is described in Authentication.
The ERP Sync agent and label stations get their own keys where they are connected, not on this page. See Create an ERP connection and Install the Omnilinker Station app.

​
Permissions

The permissions are under API keys in the role editor. You can edit, rotate and change the access of your own keys only, even with See and manage every key in the tenant. No API key can hold any of these permissions.

​
Create a key

1

Start a key

Click New API key. If you have no keys yet, the page shows Create your first API key instead: click the kind of integration you want to connect.
2

Choose what will use it

Under What will use it?, choose a template. It sets the key’s starting access; see Templates. New API key opens with Reporting & BI selected.
3

Name it

Enter a Name that says where the key runs, for example “Power BI — price report”. It needs 3 to 64 characters, and each of your keys needs a different name.
4

Check what it can do

What it can do lists the access the template gives, module by module. To change it, click Customize access…; see Choose what a key can do.
5

Choose when it expires

Under Expires, choose 30 days, 90 days, 1 year, Pick a date or Never. 90 days is selected. A key with a date works until the end of that day.
6

Add notes, if you like

Click Add notes to record who owns the key and where it runs, up to 512 characters.
7

Create the key

Click Create key. The Key created dialog opens; see Copy the key.
Choose Never only for a key someone watches: it stays valid until you delete it.

​
Templates

A template grants only what you hold yourself; the rest is left out.

​
Choose what a key can do

Click Customize access… to open Access for ”…”. It lists only what you can do yourself.
1

Pick a module

The Modules list on the left shows each module with how much of it the key can use.
2

Set each resource

For each resource, choose None, View, Everything or Custom. A resource with nothing but itself to grant shows None and Allowed. With View or Custom, the resource’s actions appear below it: click an action to turn it on or off. Turning an action on also turns on viewing what it belongs to.View all gives view access to the whole module, and Clear removes everything in it.
3

Apply

The footer counts the permissions you chose. Click Apply to go back to the key.
Other tools in the panel:
  • Search permissions finds a permission in any module, for example “export” or “price level”.
  • All and Granted show every permission or only the ones the key has.
  • Start from, shown while you create a key, replaces the selection with a template’s access.
  • Actions marked with a warning sign delete data or expose customers’ personal data. When the key has one, the panel says “This key can now delete data or see personal data.”
  • “Not listed because you don’t have them yourself: …” names the modules you cannot grant.

​
What no key can do

Some permissions are never available to an API key, even when its owner holds them and the key was given them:
  • Not for API keys: managing users, roles, features, settings and API keys; managing automation rules, custom triggers and automation settings, and running a custom trigger on records its setup excludes; changing who owns warehouse stock or product identity; marketplace and courier accounts; generating the ERP agent’s key and choosing the ERP user Omnilinker writes with; changing how long ERP send records are kept; and the background jobs dashboard. Modules made only of such permissions are listed in the panel under Not for API keys: “A key can’t manage users, keys or settings, so a leaked key can’t lock you out.”
  • Screen only: saved filters, dashboards, settings pages, the Notification Center and the manufacturer dashboard, among others. A person uses them on the screens; a key cannot. Tick Show screen-only permissions to see them in the panel, marked Screen only.

​
Copy the key

The Key created dialog shows the full key once. Omnilinker keeps only a hash of it, so nobody can show it to you again.
1

Copy it

Click Copy next to Your API key and store the key in your password manager or your tool’s secret store. Keys start with olk_.
2

See how to use it

Use it shows a request in curl, PowerShell and Python. Send the key in the X-Api-Key header, never in a URL: addresses end up in logs.
3

Test it

Click Test the key. Omnilinker calls the API with the key from your browser and shows Test passed with the user the key acts as and how many permissions it has.
4

Close the dialog

Tick I’ve stored the key somewhere safe (copying the key ticks it for you) and click Done.
If you lose the key, rotate it to get a new one; see Rotate a key.

​
The keys list

Each row shows the key’s name, the first characters of the key (its prefix), what it can do, its status, when it expires, and its actions. Your keys are grouped under Your integrations. With See and manage every key in the tenant, the group is Integrations, each key shows its owner, and the keys of the agents and stations are listed under Agents & devices, with a link to Open connection or Open stations where they are managed. Filter the list with the buttons above it: Search keys finds a key by its name, notes or prefix. API reference opens the API’s reference documentation. Click the arrow at the start of a row to see the key’s details: What it can do, Acts as, the key’s prefix, Notes, Created, Last used, Expires and, for a key that expires, the Reminder date.

​
Statuses

Last used is updated at most once every five minutes.

​
Edit a key

Open the row’s More actions menu and click Edit. You can change:
  • Name and Notes. The key itself does not change.
  • Expires: Keep, +30 days, +90 days, Pick a date or Never. +30 days and +90 days add to the current expiry date, or to today if the key has expired or has none.
  • Active: turn it off to stop the key without deleting it.
Click Save changes: “Key saved”. To change what the key can do, click Change access in the menu, or Customize access… in the edit dialog. You need Change what API keys can access. Access changes apply to the key straight away.

​
Rotate a key

Rotating gives you a new key with the same name, notes and access. The old key keeps working for a while, so you can swap it without a gap.
1

Start the rotation

Click Rotate key… in the row’s menu. A key that expires within 14 days also shows a Rotate button on its row.
2

Choose how long the old key keeps working

Under Keep the old key working for, choose Stop it now, 1 hour, 24 hours or 7 days. 24 hours is selected.
3

Choose when the new key expires

Under New key expires, choose 30 days, 90 days, 1 year, Pick a date or Never.
4

Rotate

Click Rotate key. The New key ready dialog shows the new key once; copy it as in Copy the key.
Both keys are listed until the old one stops; the old one shows Replaced. Put the new key in place before then. Only an active key that has not expired can be rotated. A key you deactivated must be reactivated first.

​
Expiry and reminders

Once a key has seven days or less to go, its owner gets a notification: “API key “…” expires in N days”, with a link to the key. A key that expires within a day says “API key “…” expires within a day”. Each key is reminded once; changing its expiry date resets the reminder. When the date passes, the key stops working. To keep the integration running, rotate the key before it expires, or extend it with Edit > Expires. Keys that expire soon are also counted on Home’s API keys card; see Home.

​
Deactivate or delete a key

1

Open the dialog

Click Deactivate or Delete… in the row’s menu. The Remove ”…”? dialog opens.
2

Choose how to remove it

  • Deactivate: stops the key now. You can turn it back on later.
  • Delete permanently: can’t be undone. The key’s history stays in the audit log.
If the key was used in the last seven days, the dialog warns: “Whatever uses it will start getting 401 errors straight away.”
3

Confirm

Click Deactivate key or Delete key: “Key deactivated” or “Key deleted”.
To turn a deactivated key back on, click Reactivate in its menu: “Key reactivated”. An expired or replaced key cannot be reactivated. When someone with See and manage every key in the tenant deactivates your key, only a person with that permission can turn it back on. The edit dialog says “Stopped by …. Ask them to turn it back on, or create a new key.”

​
When a key stops working

A program using the key gets 401 responses when:
  • the key was deactivated or deleted;
  • its expiry date passed;
  • it was rotated and the overlap you chose has ended;
  • its owner’s account was deactivated, locked out or deleted.
A call the key has no permission for is refused even though the key itself is valid. Check the key’s What it can do, and whether its owner still holds the permission.

​
Troubleshooting

Each of your keys needs its own name. Choose another one.
The date you picked has passed. Pick a later date.
The listed permissions are not available to API keys, or you do not hold them yourself. Remove them, or ask an administrator for the permission first.
You tried to edit, rotate or change the access of someone else’s key. Only its owner can. With See and manage every key in the tenant you can still deactivate or delete it.
Agent and station keys are managed where the device is connected: the ERP connection or Devices > Stations.
Someone who manages every key in your organization deactivated your key, so you cannot turn it back on yourself. Ask that person, or create a new key.
Only an active key can be rotated, once. Reactivate a deactivated key first. A key already rotated has a newer key: use that one, or rotate the newer key.
“The API did not accept the key.” Try again in a moment; if it keeps failing, contact support. “Could not reach the API” means the request got no answer, which says nothing about the key: check your connection and test again.
“You can see keys here, but creating one needs the “Create API keys” permission. Ask an administrator.”

Authentication

Send the key with your API requests.

Developers overview

What you can do with the Omnilinker API.

Permissions reference

What each permission grants a person or a key.

Users and roles

Give people the permissions they need to create keys.