Skip to content

API keys and scopes

An API key lets software act on your organisation’s data. Give each tool its own key with only the scopes it needs, so you can revoke one without breaking the others.

  • You need to be the owner or an admin (permission api.manage). Managers and staff don’t see API and webhooks in Settings.
  • API keys need the Growth plan and above. Write scopes need the Pro plan.

Go to Settings → API and webhooks.

Settings, API and webhooks: the base URL https://api.direct.eat/v1 with Copy URL and API docs buttons, and the API keys tab with a Create key button

The page shows the base URL, the current API version and two tabs: API keys and Webhooks. API docs opens the reference inside the dashboard.

  1. Click Create key.

  2. Give it a Name that says what uses it, like “Agency POS bridge”.

  3. Choose the Mode:

    • Live: real orders and menus. Starts with de_live_.
    • Test: only sees test orders, never live ones. Starts with de_test_.
  4. Tick the Permissions (scopes) it needs. menu:read and orders:read are ticked by default.

  5. Under Shops, leave All shops (including ones you add later) ticked, or untick it and choose shops.

  6. Optionally set Expires (a date) and an IP allow-list (addresses or CIDR ranges, comma separated).

  7. Click Create key.

The Create an API key dialog: Name, Mode (Live or Test), six permission checkboxes, Shops, Expires and IP allow-list fields

The key is shown once. We only store a fingerprint of it, so nobody (including direct.eat) can show it again. Click Copy, put it in your password manager or your server’s secret store, then click I’ve saved it.

Your new API key dialog with the warning This is the only time you'll see this key, a partly hidden de_live_ key and a Copy button

If you lose a key, revoke it and create a new one.

Scope What it allows Plan
menu:read Read shops, published menus and live availability (86) Growth
orders:read Read orders and the events feed Growth
customers:read Read customers. Email and phone are included only for customers who subscribed to marketing on that channel Growth
orders:write Update order status and ready time Pro
menu:write Change availability (86). Reserved: no endpoint uses it yet Pro
webhooks:manage Manage webhook endpoints. Reserved: no endpoint uses it yet Pro

A write scope includes the matching read scope: a key with orders:write can also read orders.

When you tick customers:read, the dialog warns: “Customer access returns contact details only for people who agreed to marketing. Only use it with tools you trust.”

de_live_8Hq3xY2a… live key: de_live_ + 40 letters and digits
de_test_… test key: de_test_ + 40 letters and digits

The first 8 characters after de_live_ or de_test_ are shown in the key list, so you can tell keys apart. Send the whole key as a bearer token:

Authorization: Bearer de_live_8Hq3xY2a…

Each key shows its name, LIVE or TEST, its status, the visible prefix, its scopes, which shops it can see, when it was created and when it was last used, with a request count.

The API keys tab showing one live key with its prefix, scopes MENU:READ, ORDERS:READ and CUSTOMERS:READ, All shops, created and last used, and a Revoke link

Click Revoke next to the key, then Revoke again to confirm.

Revoke confirmation: Anything using this key stops working straight away. This can't be undone; create a new key if you need one.

Anything using the key stops working straight away and gets 401 with the code api_key_revoked. This can’t be undone.

There’s no “rotate” button. To swap a key without downtime:

  1. Create a new key with the same scopes and shops.

  2. Deploy it to your software.

  3. Check last used on the old key stops moving.

  4. Revoke the old key.

  • One key per tool. Name it after the tool.
  • Start read-only. Add orders:write only for tools that really change orders.
  • Add customers:read only when the tool needs customer data.
  • Use a test key while building, then create a live key.
  • Never put a key in a web page, a mobile app or a public repository. Keys are for servers.
  • Set an IP allow-list when your server has a fixed address.
  • Set an expiry for contractors and short projects.
Status Code Why
401 invalid_api_key Missing, mistyped or unknown key
401 api_key_revoked The key was revoked
401 api_key_expired The key passed its expiry date
403 ip_not_allowed The request came from an IP address not on the allow-list
403 missing_scope The key doesn’t have the scope this endpoint needs
403 upgrade_required Your plan doesn’t include API access, or write access

More in Errors and limits.

Was this page helpful?