Authentication
How to authenticate with the Ersaal API using Bearer tokens
The Ersaal API uses Bearer token authentication. Include your token in the Authorization header on every request. API access is also restricted by the IP whitelist configured for the project.
Authorization: Bearer YOUR_API_TOKENGetting your token
- Log in to sms.lamah.com
- Go to Projects and open a project
- Add your server's public outbound IP address to the project's allowed IP list
- Copy the API token from project details
Your API calls must originate from a public IP address or CIDR range in the project's whitelist. Requests from any other IP return 401 with Unauthorized IP address. Both single addresses and CIDR ranges are supported (IPv4 and IPv6).
Security best practices
- Store tokens in environment variables, never in source code
- Each project has exactly one API token — a token authenticates as that project, so keep them separate per project
- Rotate tokens periodically from the dashboard
- Keep the IP whitelist as narrow as possible;
0.0.0.0(or0.0.0.0/0) disables the check entirely - Monitor API usage for unexpected activity
Authentication errors
All authentication failures return 401 with a message field. The message tells you which check failed:
| Status | message | Meaning |
|---|---|---|
401 | Invalid or missing token. | No Authorization header, or the token is malformed, unknown, or expired |
401 | Project is inactive. | The token is valid, but the project has been deactivated |
401 | Unauthorized IP address. | The token is valid, but the request came from an IP outside the project's whitelist |
If you receive a 401, verify the token format includes the Bearer prefix and that there are no extra spaces or newlines.
Company verification
The four send endpoints additionally require a verified company:
- Until your company is verified, single, bulk, and template sends are silently redirected to your company's registered phone number, regardless of the
receiveryou supply. The request still returns200and still consumes balance. - Sends to a contact group are blocked outright with
403and{ "message": "You can not use this feature until verify your company" }.
Read endpoints (message history, project details, balance, contacts, consumptions) are unaffected.
If the token is valid, also verify that the public outbound IP address used by your server is included in the project's allowed IP list.
Testing your token
Call the project details endpoint to confirm authentication is working:
curl https://sms.lamah.com/api/project/details \
-H "Authorization: Bearer YOUR_API_TOKEN"A 200 response means your token is valid.