Authentication - Omnilinker

Every call to the Omnilinker API carries an API key. A key acts as the person who created it, limited to the access chosen for it, and only ever inside that person’s organization. There is no separate sign-in step and no token to refresh: send the key with each request.

Send the key

Put the key in the X-Api-Key header:

curl https://omnilinker.pl/api/api-key-management/whoami \
  -H "X-Api-Key: $OMNILINKER_API_KEY"

$headers = @{ "X-Api-Key" = $env:OMNILINKER_API_KEY }
Invoke-RestMethod https://omnilinker.pl/api/api-key-management/whoami -Headers $headers

import os, requests

r = requests.get("https://omnilinker.pl/api/api-key-management/whoami",
                 headers={"X-Api-Key": os.environ["OMNILINKER_API_KEY"]})
print(r.json())

Omnilinker also accepts the header name Api-Key. It never reads a key from the URL: a key in a query string is ignored, and the request is treated as having no key. URLs end up in server and proxy logs, so keep keys in headers. Keys start with olk_, which makes a leaked key easy to spot in logs and secret scanners. Keys created before this prefix was introduced do not have it and keep working.

Get a key

Open API keys

In Omnilinker, open API keys from the main menu (it opens Settings > Integrations > API keys). You need the API keys and Create API keys permissions, under API keys.

Start a new key

Click New API key. Under What will use it?, pick the template closest to your integration; see Templates. The key starts with that template’s access, limited to what you can do yourself.

Name it and choose when it expires

Enter a Name that says where the key runs, 3 to 64 characters, for example the system and the job. Under Expires, choose 30 days, 90 days (the default), 1 year, Pick a date or Never. Optionally add Notes, such as who owns the integration.

Adjust the access, if needed

Under What it can do, click Customize access… to add or remove permissions, then click Apply.

Create the key and copy it

Click Create key. The key is shown once, under Your API key: click Copy and store it in your secrets manager. Omnilinker keeps only a hash of it, so it cannot show it again. If you lose it, rotate the key to get a new one.

Test it

Click Test the key. Omnilinker calls the API with the new key from your browser and shows Test passed, with the user the key acts as and how many permissions it has. Then select I’ve stored the key somewhere safe and click Done.

Creating, rotating and revoking keys is covered in detail in API keys.

Check a key from your code

GET /api/api-key-management/whoami answers with the key’s own details. It needs no permission, so any valid key can call it. Make it the first call of a new integration, or a health check:

{
  "apiKeyId": "<key-id>",
  "name": "Power BI — price report",
  "displayPrefix": "olk_<prefix>",
  "purpose": "Integration",
  "userId": "<user-id>",
  "userName": "<owner-user-name>",
  "tenantId": "<organization-id>",
  "tenantName": "<organization-name>",
  "expirationTime": "2027-01-11T09:30:00Z",
  "grantedPermissions": [
    "Ordering.Orders",
    "Ordering.Journal"
  ]
}

grantedPermissions lists what the key can really do right now: its own grants, cut down to what its owner still has and to what keys may hold at all. expirationTime is null for a key that never expires.

What a key can do

A key’s access is the overlap of two things:

The key’s own grants, chosen when it was created or later with Change access.
Its owner’s permissions. A key can never do more than the person who created it. If that person loses a permission, the key loses it too.

A key stops working, and every call with it answers 401 Unauthorized, when:

it expires,
someone deactivates or deletes it,
it was rotated and the old key’s overlap has ended,
its owner is deactivated, locked out or deleted.

What a key can never do

Some permissions are never available to a key, whatever its grants say. On the access panel they are listed under Not for API keys: “A key can’t manage users, keys or settings, so a leaked key can’t lock you out.” They include:

managing users, roles, organizations, features, settings and API keys;
managing marketplace accounts and courier accounts, which hold your credentials for those services;
creating or changing automation rules and custom triggers, running a custom trigger outside its allowed statuses, and changing automation settings;
changing who owns product identity or a warehouse’s stock, generating ERP agent keys, and choosing the ERP user Omnilinker writes with.

Other permissions only make sense on a screen, such as saved filters, dashboards and settings pages. Keys cannot use them either. To see them on the access panel, turn on Show screen-only permissions. Everything in Notification Center is screen-only. An endpoint that requires a signed-in person but no particular permission refuses keys with 403 Forbidden. whoami is the exception.

Templates

Template	For	Access it starts with
Reporting & BI	Power BI, Excel, Looker Studio	Reads catalog, prices, offers, orders and stock. Marked READ-ONLY.
Catalog & price sync	A PIM or web shop that pushes products and prices	Creates and updates products, brands, categories, tags and price levels. Never deletes.
Orders integration	n8n, Make or your own middleware	Creates and updates orders and sets their status, reads order statuses, sources and the order journal, reads shipments, downloads labels, and reads contacts.
Custom	Anything else	No access. Choose each permission yourself.

A template grants only the permissions you hold yourself; the rest are left out. No template includes View personal data, under Orders. Without it, the buyer’s personal data in orders comes back masked, and changing an existing order’s buyer, delivery address, invoice details or pickup point is refused. If your integration reads or changes buyers’ names, addresses or contact details, add that permission with Customize access…. The access panel then warns: “This key can now delete data or see personal data.”

Keep keys safe

One key per integration. If one system is compromised, you revoke one key and the rest keep working. The name is unique per person, which helps you tell keys apart.
Store the key as a secret, in an environment variable or a secrets manager, never in source code or in code that runs in a browser.
Give it the least access. Start from the closest template and remove what the integration does not use.
Let it expire. Choose Never only for a key someone watches. Omnilinker sends the owner a notification 7 days before a key expires: “Rotate it before then, or whatever uses it will stop working.”
Rotate instead of re-creating. Rotate key… gives you a new key with the same name, notes and access, and keeps the old one working for the time you choose under Keep the old key working for: Stop it now, 1 hour, 24 hours or 7 days. Switch your system to the new key within that time.
Watch for unused keys. The list shows when each key was last used, to within a few minutes, and filters keys Unused 30+ days. Deactivate what nobody uses.

People sign in to the web app with their user name and password; that sign-in is not for programs. You cannot register your own OAuth or OpenID Connect client in Omnilinker, so use an API key for every integration. ERP agents and label stations also use API keys, but they get them where they are connected: on the ERP connection and on Devices > Stations. Those keys appear on the API keys page under Agents & devices and are managed where the device is connected. See Install the agent and Install the station app.

Troubleshooting

401 Unauthorized on every call

Check that the header is X-Api-Key (or Api-Key) and that the value is the whole key, starting with olk_. A key in the URL is ignored.
Check that the key is still active: on the API keys page, a key that stopped shows Expired, Inactive or Replaced.
Check that the person who created the key can still sign in. A key stops when its owner is deactivated, locked out or deleted.

403 Forbidden on one endpoint

Call whoami and look for the permission in grantedPermissions. If it is missing, add it with Change access, or ask the key’s owner: only the owner can change a key’s access, and it takes the Change what API keys can access permission.
If the owner lost the permission, the key lost it too. Ask an administrator to give it back to the owner.
The endpoint may need a permission keys can never hold, or no permission at all; see What a key can never do.
The module may not be enabled for your organization; see Modules and feature availability.

Test failed when I created the key

“Test failed” followed by a status code means the API did not accept the key. Wait a moment and click Test again; 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.

I lost the key

Omnilinker cannot show a key again. Open the key’s menu and click Rotate key… to get a new one with the same access, then update your system. Rotating needs the Edit and rotate API keys permission.

API keys

Create, edit, rotate and revoke keys.

Developer overview

Conventions, paging and errors.

Permissions reference

What each permission allows.

Webhooks and change feeds

Follow order changes with the order journal.

​Send the key

​Get a key

​Check a key from your code

​What a key can do

​What a key can never do

​Templates

​Keep keys safe

​Other ways to sign in

​Troubleshooting