What is an API key?
An API key is a short string of characters that identifies your application to a server. It is the simplest and most common way to authenticate API requests. This guide explains what API keys are, how they work, and how to use them safely.
What an API key is
An API key is a long, randomly generated string — something like sk_live_4xK9mP2vQ8nR7... — that you include with every request you make to an API. Think of it like a password, but for your application rather than a person.
When the server receives a request, it looks up the key, confirms it belongs to a valid account, and then processes the request under that account's permissions and credit balance. No key, no response.
Simple version
An API key is how the server knows who is asking — and whether they are allowed to ask.
How it authenticates a request
With Cargo Docked (and most REST APIs), you pass your key in a request header called Authorization. The value is the word Bearer, a space, and then your key:
Authorization: Bearer sk_live_4xK9mP2vQ8nR7...
Every HTTP request you make to the API must include this header. If the key is missing or wrong, the server returns a 401 Unauthorized error. If your account is out of credits, it returns a 402 Payment Required.
Keeping your key safe
An API key has the same power as a username and password. Anyone who has it can make requests charged to your account. Treat it accordingly.
Rule of thumb
API keys belong on the server, not in the browser. Your backend makes the API call; your frontend talks to your backend.
For local development, a .env file is a common place to keep secrets. Make sure .env is in your .gitignore so it is never committed.
# .env CARGO_DOCKED_API_KEY=sk_live_4xK9mP2vQ8nR7...
Credits and rate limits
An API key is tied to an account, and that account has a credit balance. With Cargo Docked, one credit equals one successful container lookup. Credits do not expire — buy them once and use them whenever you need.
Rate limits are a separate concept: they cap how many requests you can make per second or per minute, regardless of your credit balance. This prevents a runaway script from hammering the API. If you hit a rate limit, the API returns a 429 response and you should add a short pause before retrying.
Making your first request
Once you have your API key from the dashboard, you can make a real request in under a minute. The simplest way to test it is with curl in a terminal:
curl https://api.cargodocked.com/v1/containers/MSCU7432105 \ -H "Authorization: Bearer YOUR_API_KEY"
Replace YOUR_API_KEY with your actual key and MSCU7432105 with a real container number. The response is a JSON object with the container's current status, route, vessel, and latest milestone events.
If you prefer to test without using live credits, the sandbox environment returns realistic fake data — perfect for building and testing before you go to production.
Frequently asked questions
Where do I find my API key?
Log into your Cargo Docked dashboard and go to the API Keys section. You can create, rename, and revoke keys there.
Can I have more than one API key?
Yes. It is good practice to use separate keys for different environments — one for development, one for production — so you can revoke one without affecting the other.
What happens if I expose my key by accident?
Revoke it immediately from the dashboard. Revoking a key makes it invalid within seconds. Then generate a new key and update your environment variables.
Up next
What is a container tracking API?