PurpleTRAC API authentication

PurpleTRAC takes two credentials on every request: a username and an API key. Both go in the query string. There is no token exchange, nothing expires on a timer, and there is no sign-in endpoint.

This is an older scheme than the api-key header used by Insights. It is still how PurpleTRAC works in production, and we are migrating everything to API keys.

Sending your credentials

Add username and api_key to the query string on every call, alongside whatever other parameters the endpoint takes.

All requests must be made over HTTPS. Requests over HTTP are not processed.

Keep credentials out of your source

Read both values from environment variables or a secrets manager. Because they travel in the query string, they also reach anything that logs full request URLs, so check what your HTTP client, proxy and observability stack retain.

Getting credentials

Credentials are issued by your Pole Star representative as part of onboarding. There is no self-service portal and no way to generate a second pair yourself. If you have not received yours, or you need them rotated, contact your representative.

Checking they work

The vessel search endpoint is the cheapest call to verify a credential pair against. It needs nothing but your credentials.

A 200 with a JSON body means the pair is good.

What the API key does not control

Your credentials authenticate you. What they reach is set separately, by the account configuration agreed at onboarding: which addons are enabled, which watchlists are selected, and the thresholds on individual checks.

That distinction matters when reading errors. A 403 from PurpleTRAC means the endpoint needs a feature your account does not have, not that your credentials are wrong. Wrong credentials give you a 401.

Symptom	Likely cause	Fix
`401 Unauthorized`	`username` or `api_key` missing, mistyped, or not yet active	Check both values. Contact your representative if they were issued recently
`403 Forbidden`	The endpoint belongs to an addon that is not enabled for your account. On `PUT /transaction/{id}/voyage_update` it means the transaction belongs to another account	Ask your representative whether Carbon Rating, BL Verification or Container Screening is on your contract
`404 Not Found`	The transaction or resource does not exist	Check the id. Ids are scoped to the account that created them

Errors & Status Codes covers the response shapes in full.

How this compares with the rest of the portfolio

Product	Scheme	Status
Insights, all categories	`api-key` header	Current
PurpleTRAC	`username` and `api_key` query parameters	Legacy, still in production
Weather	OAuth 2.0 Token (1 hour)	Legacy
Podium	OAuth 2.0 Token (1 hour)	Legacy
MTI	OAuth 2.0 client credentials (Keycloak)	Current

An Insights key will not work here, and a PurpleTRAC pair will not work against Insights. If you integrate with both, you hold two sets of credentials.

PurpleTRAC Authentication

Sending your credentials#

Getting credentials#

Checking they work#

What the API key does not control#

How this compares with the rest of the portfolio#

Sending your credentials

Getting credentials

Checking they work

What the API key does not control

How this compares with the rest of the portfolio