Get started
Provision API keys
An API key is the only credential your server needs to call Shiftwa. We show the plaintext once — after that only the prefix is visible.
Create a key in the dashboard
- Open app.shiftwa.dev → API keys → click Generate.
- Give it a descriptive name (e.g. 'crm-prod', 'cs-staging') so it's easy to trace in the audit log.
- Pick the mode: pinned (locked to 1 number) or pool (rotation). Pinned suits accounting / ticketing services with a dedicated number.
- Copy the plaintext key immediately. Once the dialog closes we never expose it again — only the hash + prefix remain.
Use the key in a request
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxasync function send(text, to) {
const res = await fetch("https://api.shiftwa.dev/v1/messages/send", {
method: "POST",
headers: {
"X-API-Key": process.env.SHIFTWA_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ to, text }),
});
if (!res.ok) throw new Error(`Shiftwa ${res.status}`);
return res.json();
}Pinned vs pool
If your business maps one number per service (e.g. an invoicing number separate from a delivery-notification number), create one pinned key per service. If you only need general broadcasts / notifications, a pool key with rotation is enough.
| Mode | Behavior | onPinFailure |
|---|---|---|
pinned + strict | Sends only via the pinned number. If the pin is disconnected / banned: 503. | strict |
pinned + fallback | Try the pin first. If unavailable, silently fall back to the pool rotation (visible in logs as sender.source = 'pinned_fallback'). | fallback |
pool | Every request picks a healthy sender. Override per request with a sender hint. | — |
Key management endpoints
These endpoints use the dashboard JWT, not an API key — so only a signed-in admin can call them.
POST
/v1/auth/api-keysnamestringrequired- Internal label.
pinnedNumberIduuid | null- ID of the number to pin to. Null = pool.
onPinFailure'strict' | 'fallback'- Only relevant when pinned. Default strict.
DELETE
/v1/auth/api-keys/:idRevokes the key — irreversible. Subsequent requests with that key return 401 INVALID_API_KEY.
Key rotation (best practice)
- Generate the new key in the dashboard.
- Deploy with env pointing at the new key. Let both run in parallel for 1–2 hours.
- Verify there's no more traffic on the old key (check last_used_at in the dashboard).
- Revoke the old key. Done.