V1
API v1•Authentication
Authentication
All Emess API v1 requests require a JSON Web Token (JWT) obtained by exchanging your application's App ID and Secret Key.
Overview
You can create and manage applications inside your Organization Dashboard. Each application receives a unique appId and secretKey.
- Application names are strictly limited to 16 characters to keep SMS message headers predictable and maintain single-segment billing whenever possible.
- Tokens issued by
POST /api/v1/auth/tokenare valid for 1 hour. - We recommend caching and reusing the JWT in your backend until shortly before it expires rather than requesting a new token on every SMS call.
POST/api/v1/auth/token
Authenticate your application credentials and receive a signed Bearer token.
Parameters (Body)
| Name | Type | Required | Description |
|---|---|---|---|
| appId | string | Yes | Your application's App ID |
| secretKey | string | Yes | Your application's Secret Key |
Response (200 OK)
Response (200 OK)
{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
Using the Bearer Token
Pass the token in the Authorization HTTP header on all subsequent calls to /api/v1/*:
HTTP Headers
Authorization: Bearer <your_jwt_token>Content-Type: application/json
Error Codes
- 400 Bad Request:
{ "message": "Missing appId or secretKey" } - 401 Unauthorized:
{ "message": "Invalid credentials" }or expired/missing Bearer token on protected routes. - 500 Internal Server Error:
{ "message": "Server configuration error" }