Authentication

Every request needs a Personal Access Token, sent in a header. There is no OAuth flow, no client registration and no key to request from us — you create the token yourself and it works immediately.

Creating a token

1. Sign in to Cargoplot and open your profile.
2. Go to Access tokens.
3. Create one, and give it a name you will recognise in six months.
4. Copy it now. It is shown once. We store only a hash, so we cannot show it to you again or recover it if you lose it.

A token carries your own permissions. It can read exactly what you can read in the app — no more — and if your access changes, the token's access changes with it.

Using it

Send it in the X-Cargoplot-Key header:

curl -H 'X-Cargoplot-Key: <userID>|<uuid>' \
  'https://api.cargoplot.com/v1/shipment'

The token has two parts joined by a pipe: your numeric user ID, then a secret. Send the whole string exactly as it was given to you — both halves are part of the credential.

Not a Bearer token: Authorization on this API is for the browser session the app itself uses, and sending your access token there will not authenticate you.

If it does not work

A missing, malformed or revoked token gives you:

{ "message": "invalid API key" }

with status 401. The message is deliberately the same for all three, so an attacker cannot use the response to learn whether a token exists.

If you get a 401 you did not expect, check in this order: the header name is spelled exactly X-Cargoplot-Key; the token includes the <userID>| prefix; the token has not been revoked in your profile.

Revoking

Delete a token from the same Access tokens screen. It stops working immediately — there is no grace period and nothing to wait for. Revoke rather than rotate if a token may have leaked: a leaked token is usable by anyone until you do.

Create a separate token per integration. One token per script means you can revoke the one that leaked without taking down everything else you have built.

Keeping it safe

There is no browser-based "try it out" on this site, deliberately — we would rather not invite anyone to paste a live credential into a web page.