Authentication

Every request carries a project API key as a Bearer token.

HTTP

GET /v1/account/balance HTTP/1.1
Host: api.nopexo.com
Authorization: Bearer nxk_test_9fK2…

Keys belong to a project and an environment

Prefix	Environment	What happens
`nxk_test_`	Sandbox	Simulated delivery, free, works on any project. OTP responses include testCode.
`nxk_live_`	Production	Real messages through Ghanaian networks, charged to your wallet. Only for projects in production.

A key only sees its own project and environment: a message or verification created with a sandbox key is not visible to a production key, and another project’s IDs are simply “not found”.

Permissions (scopes)

Give each key only what it needs. A request outside the key’s scopes fails with INSUFFICIENT_SCOPE and names the missing scope.

Scope	Allows
`sms:send`	POST /v1/sms/send, POST /v1/sms/bulk
`sms:read`	GET /v1/sms/{messageId}, /v1/sms/bulk/{batchId}, /v1/sms/reports
`otp:send`	POST /v1/otp/send, POST /v1/otp/resend
`otp:verify`	POST /v1/otp/verify, GET /v1/otp/{requestId}
`account:read`	GET /v1/account/balance

Rotating and revoking keys

Rotate issues a new key with the same name, environment and scopes. Choose how long the old key keeps working — now, 1 hour, 24 hours or 7 days — so you can deploy the new one without downtime.
Revoke stops a key immediately. Do this if a key may have leaked.
The dashboard shows each key’s prefix, scopes and when it was last used. The full key is shown only once, when it’s created.

Keep keys on your server

Store keys in environment variables or a secrets manager. Never ship them in web pages, mobile apps or source control.

Authentication errors

Code	HTTP	Meaning
`INVALID_API_KEY`	401	Missing, wrong, expired or revoked key.
`INSUFFICIENT_SCOPE`	403	The key lacks the scope in requiredScope.
`PROJECT_NOT_ACTIVE`	403	The project is disabled or archived.
`PROJECT_NOT_IN_PRODUCTION`	403	A production key was used while the project is in sandbox.
`RATE_LIMITED`	429	Too many requests for this key this minute (default 120). Honour Retry-After.