Cargoplot APICargoplot API
API docs
OpenAPI spec

Authentication

Every request needs a Personal Access Token, sent in a header. The API has no OAuth flow, no client registration and no key to request from us — you create the token yourself and it works immediately. (An AI assistant is the exception: it signs you in instead, see Connect an AI assistant.)

Creating a token

  1. Sign in to Cargoplot and open your profile.
  2. Go to API/MCP access.
  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 do exactly what you can do in the app — no more — and if your access changes, the token's access changes with it. That covers reading your organization's records and, since inquiries became writeable, creating and changing its inquiries: a token can raise, update, cancel and delete them in your name, as you can in the app. It can also move a shipment's cargo-ready date until the cargo is picked up, and change the shipment's client references until it is completed or cancelled.

Using it

Send it in the X-Cargoplot-Key header:

bash
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:

json
{ "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 API/MCP access 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

A Personal Access Token is a password that reads your company's shipping data and can raise inquiries in its name. Treat it like one: keep it in a secret store or an environment variable, never in a repository, a frontend bundle, a URL or a support ticket.

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.