// authentication
Authentication
Every request authenticates with an API key passed in the X-API-Key header. Keys are issued, scoped, and revoked from the dashboard.
curl https://api.eksms.com/v1/messages \
-H "X-API-Key: eksms_live_74e34159e0db878c9e00ed329491e4b1"
Keys look like eksms_live_…. The full secret is shown once, at creation time - we only store a hash, so we can never show it again. Store it in a secret manager or environment variable.
app.eksms.com/api-keys
NameKeyScopes
Productioneksms_74e3••••••••••••messages:send
CI / stagingeksms_9a2f••••••••••••messages:read
New key - copy it now
eksms_74e34159e0db878c9e00ed329491e4b1
Scopes
Each key carries one or more scopes that limit what it can do:
| Scope | Grants |
|---|---|
| messages:send | Send messages via POST /messages. |
| messages:read | List and retrieve messages and delivery status. |
A request with a key that lacks the required scope returns 403 with code API_KEY_SCOPE_DENIED. Issue send-only keys to client services and read keys to dashboards.
Security best practices
- Never expose a key in client-side code (browser, mobile bundle). Call EK SMS from your server.
- Scope narrowly. A service that only sends OTPs needs only
messages:send. - Rotate regularly. Create a new key, deploy it, then revoke the old one - there is no downtime because both work until you revoke.
- One key per environment / service so you can revoke a leak without taking everything down.
Treat keys like passwords
Anyone with your key can spend your credits. If a key leaks, revoke it immediately from the dashboard - revocation takes effect at once.
Next: Send a message