🔑 Authorization

Authorization via API key

---

Every Trident (v3) endpoint is authenticated with an API key. A key belongs to your organisation, not to the user who created it, and works for one environment: Production or UAT.

Create an API key

---

1. Sign in to the API Console at console.dockflow.com with your Dockflow account. If you do not have an account yet, contact [email protected].
2. Open API Keys and stay on the API keys tab.
3. Click Create Key and fill in:
   • Name: a label for your own bookkeeping, up to 80 characters (e.g. Production Integration).
   • Environment: Production or UAT.
   • Scopes: what the key is for: Downstream (send tradeflows and documents), Upstream (read tracking) and/or Widget. Widget cannot be combined with other scopes.
4. Copy the key. It is shown only once. Dockflow stores a hash, so a lost key cannot be recovered. Create a new one instead.

note

You will only see the API key once! Make sure to save it before navigating away.

Scopes

---

Scope	Use it for
Downstream	Sending tradeflows and documents: Downstream, Documents
Upstream	Reading tracking updates: Upstream
Widget	The tracking widget only: Widget Embed and Widget API

A Widget key is published in your web page, so it is kept apart from the others: it works only on the widget, and the widget accepts no other key. Create a separate key for each website you embed the widget on, so you can revoke one without touching the others.

Key format

---

{env}_{organisation-slug}_{secret}

Part	Example	Notes
env	prod or uat	The environment the key works for.
organisation-slug	acme-logistics	Your organisation's name, lower‑cased with punctuation dropped and spaces replaced by -.
secret	f36d0c4e… (43 characters)	Random, URL‑safe base64.

For example: prod_acme-logistics_Zk3n1c0Q2m9...

Send the key

---

Put the key in the Authorization header. The bare key and the Bearer scheme are both accepted:

curl -H "Authorization: prod_acme-logistics_Zk3n1c0Q2m9..." https://api.dockflow.com/v3/upstream
curl -H "Authorization: Bearer prod_acme-logistics_Zk3n1c0Q2m9..." https://api.dockflow.com/v3/upstream

Environments

---

Key prefix	Host	Data
prod_…	https://api.dockflow.com/v3	Your organisation
uat_…	https://uat.dockflow.com/v3	A separate UAT organisation, created automatically the first time a key is created for your organisation

A key only works on its own host. A uat_ key never reads or writes production data. See UAT environment.

Manage keys

---

The API keys tab lists every key with its name, environment, scopes, creation date and last used time. You can rename a key or revoke it; scopes are fixed when the key is created. Revocation takes effect immediately and cannot be undone.

Authentication errors

---

Error bodies have the shape {"error": "<message>", "status": <code>}.

Status	Message	Cause
401	Missing or malformed Authorization header.	No Authorization header, or a value that is not a key.
400	Token format invalid.	The value after Bearer is not in the {env}_{slug}_{secret} shape.
403	Token environment (uat) does not match host (prod).	A uat_ key sent to api.dockflow.com, or a prod_ key sent to uat.dockflow.com.
401	Token not recognised.	Unknown key, or the key was mistyped or truncated.
403	Token has been revoked.	The key was revoked in the API Console.
403	Token lacks the "widget" scope. (or "downstream", "upstream")	A Widget key used on a data endpoint, or a data key used on the widget.