Authentication
Bob Box integrations use an API key as a bearer token. Every request carries the same header:
Authorization: Bearer <api_key>
| Credential | Who it's for | How you get it | Expires |
|---|---|---|---|
| API key | Server-to-server integrations (courier and delivery platforms) | Created under Settings → API keys, or issued with an API user. | No |
API keys resolve to the account and permissions assigned to them.
An unknown or revoked token returns 401, with the body Authentication error: authentication failed, please check your API key.
Sending no Authorization header returns 403, with You're not logged in. Please log in and try again. A valid API key whose role lacks the endpoint's permission also returns 403, with You do not have access to the requested resource.
All three are plain text, not the JSON { "message": ... } envelope the rest of the API uses — they are returned before the handler runs.
API keys
Getting a key
You can create your own key. Sign in to the dashboard as the Bob Box account owner, open Settings → API keys, and create one. The same page deletes keys you no longer want.
Your Bob Box contact can also create an API user for you instead.
Either way, the key is shown once, in full, at that moment.
Copy it then and store it somewhere safe. Afterwards it is only ever displayed masked, as abc***xyz. If it is lost, create a new key and delete the old one.
Using it
Send it as a bearer token on every request:
curl -G "https://api.bobbox.co.za/v2/account/locations" \
-H "Authorization: Bearer 4f3c9b1a72e04d5fa9c8e6b0d1a2f3c4"
That is the whole authentication flow.
What the key can do
The API user carries a role, and that role decides which endpoints the key may call. A key issued for your account reads and writes your own account's locations and reservations.
Keeping it safe
- Treat it as a password. It grants full access to your account's data and never expires.
- Server-side only. Never put it in a mobile app, browser JavaScript, or a public repository — there is no way to scope or time-limit it.
- HTTPS only. The API is HTTPS-only; do not build anything that would send the key in the clear.
- Rotating means replacing. A key cannot be rotated in place. Create a second key under Settings → API keys, cut your integration over to it, then delete the old one from the same page.