Getting started
Authentication and API keys
Every /v1 request carries an API key as a bearer token. The key prefix determines the mode: sk_test_ is sandbox, sk_live_ is production. Keys are stored as SHA-256 hashes, so a lost key can only be replaced.
How do I authenticate?
Send your API key as a bearer token in the Authorization header. An X-API-Key header is accepted as an alternative for clients that cannot set Authorization.
curl https://api.sendozi.com/v1/me \
-H "Authorization: Bearer $SENDOZI_API_KEY"curl https://api.sendozi.com/v1/me \
-H "X-API-Key: $SENDOZI_API_KEY"GET /v1/me is the cheapest way to confirm a key works: it returns the workspace the key belongs to without sending anything or spending anything.
Sandbox and production keys
| Prefix | Mode | Behaviour |
|---|---|---|
| sk_test_ | Sandbox | Records the send, calls no provider, debits nothing. Runs recipient, policy and suppression checks. |
| sk_live_ | Production | Runs every gate, calls the provider and debits the wallet. |
How keys are stored
- The secret is shown once, at creation. Sendozi stores only a SHA-256 hash of it.
- A lost key cannot be recovered. It is revoked and replaced.
- Each key belongs to one workspace and carries its own scopes and status.
- GET /v1/api-keys lists your keys in redacted form: id, name, mode, prefix, status, scopes and last use.
- Ops can block a key independently of your account. A blocked key returns api_key_blocked.
Handling keys safely
- Environment variables, never source control
- A key committed to a repository is compromised the moment the repository is shared, and rewriting history does not un-share it. Rotate rather than delete the commit.
- Server-side only
- A Sendozi key sends messages and spends a wallet balance. It has no place in a browser bundle, a mobile app or anything a user can decompile. Proxy through your own backend.
- One key per system
- Separate keys for your web app, your background workers and your internal tooling. When one leaks you rotate one, and last_used_at tells you which is which.
- Watch last_used_at
- A key that has not been used in months is a key nobody will miss when it is revoked - and one nobody is watching if it leaks.
- Restrict where requests come from
- GET /v1/api-whitelists shows the IPs and origins allow-listed for your workspace. Narrowing them limits what a leaked key is worth.
Rotating a key without downtime
- 1
Create the replacement first
Two active keys can serve the same workspace at once, so there is no gap.
- 2
Deploy the new value
Update the environment variable and roll your services.
- 3
Confirm the old key has gone quiet
Check last_used_at on the old key in GET /v1/api-keys before removing it.
- 4
Revoke the old key
Only after nothing has used it for a full deployment cycle.
If a key is known to be leaked, invert the order: revoke first and accept the outage. A short interruption is cheaper than an unknown party spending your wallet.
Authentication errors
| Code | Status | Meaning |
|---|---|---|
| unauthorized | 401 | Missing, malformed or unrecognised key |
| forbidden | 403 | Authenticated, but not permitted for this action |
| api_key_blocked | 403 | The key was blocked by Sendozi Ops |
| workspace_suspended | 403 | The workspace cannot send production traffic |
Frequently asked questions
- Where do I get a Sendozi API key?
- From the API keys section of the Sendozi Console. The secret is displayed once at creation; afterwards only a hash is stored, so it cannot be shown again.
- What is the difference between sk_test_ and sk_live_?
- sk_test_ is sandbox: the send is recorded, no provider is called and nothing is debited. sk_live_ is production: every gate runs, the provider is called and the wallet is charged. The endpoints and the base URL are identical.
- Can I use a Sendozi API key in a mobile app or frontend?
- No. The key can send messages and spend your balance, and anything shipped to a device can be extracted. Call Sendozi from your own backend and expose only what your app needs.
- I lost my API key. Can support recover it?
- No. Keys are stored as SHA-256 hashes, so nobody at Sendozi can read one. Create a replacement, deploy it, then revoke the old key.
Related reading
Getting started
Quickstart: send your first SMS
Get an API key, send a sandbox SMS, read the response envelope, register a delivery webhook and move to production. A complete first integration in one page.
Getting started
Sandbox testing
How Sendozi sandbox mode works, exactly which checks it runs, what it does not exercise, and how to structure tests so a passing sandbox run means something.
Reliability
Errors and the response envelope
The Sendozi response envelope, every error code with its status and meaning, which errors are worth retrying, and how request_id is used to trace a failure.
Channels
SMS API reference
Endpoints, request fields, routing, batching, sender ID management and page-based cost for sending SMS to Nigerian numbers through the Sendozi API.