Authentication
Every request to a Safecube API is authenticated with an API key. The key is sent in a header named API_KEY: there is no session, no cookie and no token exchange, and the same key authenticates the Container Tracking, Webhooks, Shipment Management, Ports Intelligence and Congestion APIs.
Find your API key
The Safecube API key is displayed in the Safecube web application, on the page https://app.safecube.ai/api/credentials. To reach it from the application, open Developers in the sidebar, then the API Credentials tab. Only an Admin or an Owner of the workspace can open it. Each workspace has a single key. The tab is described in API credentials.
The page shows a field named API Key, with the notice "This key must be kept confidential". The key is masked by default:
- the eye toggle next to the field reveals the key;
- the copy button copies the key to the clipboard;
- the Rotate API key button replaces the current key with a new one. The current key is invalidated immediately, with no grace period: every request still sent with it fails, so update your applications with the new key. Webhooks already set up keep delivering.
Send the API key
Add the API_KEY header to every request, whatever the API and the endpoint. The example below calls the Container Tracking API with the free test shipment ZZZZ0000000.
curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000" \
-H "API_KEY: $SAFECUBE_API_KEY"
The header name is API_KEY, in full and with an underscore, and the key is sent as is, with no Bearer prefix.
A request with a missing or invalid key is rejected with 401 Unauthorized or 403 Forbidden, depending on the API. The reference page of each endpoint lists the status codes it returns.
Access to each API
One API key authenticates every Safecube API, but some APIs also check that the key has been granted access to them. The Ports Intelligence API requires that access explicitly, and the Congestion API requires access to the Congestion product. A key without the required access is rejected on the endpoints of that API.
Headers
Besides API_KEY, a few standard HTTP headers are mandatory on a Safecube API request. HTTP clients — curl, an SDK, an HTTP library — usually generate them automatically.
| Header | When it is mandatory | Purpose |
|---|---|---|
API_KEY | Always | Authenticates the request with your Safecube API key |
Host | Always (HTTP/1.1 and later) | Hostname of the server receiving the request: api.sinay.ai |
Content-Type | When the request has a body (POST, PUT, PATCH) | Format of the request body: application/json |
Content-Length | When the request has a body | Length of the request body, in bytes |
A request with a JSON body therefore carries these headers:
POST /webhook/api/v1/endpoint HTTP/1.1
Host: api.sinay.ai
API_KEY: <your API key>
Content-Type: application/json
Content-Length: 411