API keys and base URLs
Every request carries your team's API key in an apiKey header. A sandbox key works only at the sandbox base URL, and a live key only at the live one.
You need a role that can manage developer settings: Owner, Admin, or a custom role with Manage API Keys and Webhooks.
Two kinds of key
| Sandbox key | Live key | |
|---|---|---|
| Made in | Test mode | Live mode |
| Base URL | https://sandbox-api.ponitor.com | https://api.ponitor.com |
| Messages and top-ups | Simulated. Nothing reaches a real phone | Real |
| Money | Your test balance | Your account balance |
| Available | From the day your team signs up | Once your compliance review is approved |
A key sent to the other base URL is refused with 401 Unauthorized. So a sandbox key left in production code fails on its first call, rather than quietly sending nothing.
Store the key and its base URL together, for example as PONITOR_API_KEY and PONITOR_BASE_URL, with sandbox values in staging and live values in production.
Create a key
- In the app, choose Test or Live in the top bar, for the kind of key you want.
- Open Settings › Developers › API Keys.
- Choose Generate API Key.
- Copy the key. It's shown once.
Keys don't expire. You can have several at once.
Turn on each API
A key calls only the APIs your team has turned on. Turn them on under Subscribed APIs, on the same page.
| API | Path | For |
|---|---|---|
| Messaging API | /messaging/v1 | SMS and WhatsApp |
| Airtime API | /airtime/v1 | Airtime and data bundles |
A change applies to all your team's keys at once. When you turn an API off, no key can call it.
Send the key
Put the key in the apiKey header of every request:
curl $PONITOR_BASE_URL/messaging/v1/messages/e2c38865-dc0a-4299-baef-c07a9bfa9c33 \
-H "apiKey: $PONITOR_API_KEY"
The key belongs to your team, not to a person. Anyone who has it can send messages and spend your balance, so keep it on your server, in an environment variable or a secrets manager.
Mobile apps, browser JavaScript and public repositories expose the key. Call Ponitor from your own server.
Rotate or revoke a key
To replace a key without downtime:
- Generate a new key.
- Deploy it to your servers.
- Paste the old key under Revoke API Key, on the same page.
A revoked key stops working at once, and you can't restore it. Settings › Team › Activity records each key generated and revoked, by its last few characters.
When a key is refused
| Status | Why | Fix |
|---|---|---|
401 Unauthorized | The apiKey header is missing, the key is wrong or revoked, or it was sent to the other base URL. | Check the header name, the key, and that the base URL matches the key. |
403 Forbidden | The key is valid, but the API isn't turned on, or your team is suspended or hasn't completed compliance. | Check Subscribed APIs, and your team's status in the app. |
Ponitor doesn't act on a refused request. Send it again once you've fixed the problem.