API¶
Authentication¶
Requests send a token in the Authorization header:
Authorization: Bearer <token>
The token is either:
- an access token, from log in or refresh the access token, valid for 15 minutes;
- an API token, which starts with
ellasmsc_.
These paths take no token: GET /api/v1/status, GET /api/v1/metrics, GET /api/v1/openapi.yaml, POST /api/v1/init, and POST /api/v1/auth/login, /refresh and /logout.
Roles¶
| Role | role_id |
Allows |
|---|---|---|
| Admin | 1 |
Everything. |
| Read Only | 2 |
Reading messages, Diameter, operator and delivery settings. |
| Network Manager | 3 |
Read Only, plus sending messages and updating operator and delivery settings. |
| Submitter | 4 |
Sending messages, and reading the messages it sent. |
An API token has the role of its user, but cannot create API tokens, change a password, or manage users.
Responses¶
Ella SMSC's API responses are JSON objects. A successful response carries a result:
{
"result": "Result content"
}
A failed response carries an error:
{
"error": "Error message"
}
GET /api/v1/metrics returns text in the Prometheus exposition format, GET /api/v1/openapi.yaml returns YAML, and unknown paths and methods answer in plain text.
Times are RFC 3339, in UTC.
OpenAPI Specification¶
The full API is described by an OpenAPI 3.1 specification embedded in the binary. Fetch it from any running Ella SMSC instance:
GET /api/v1/openapi.yaml
Status codes¶
- 200 - Success.
- 201 - Created.
- 204 - No content.
- 400 - Bad request.
- 401 - Missing, invalid or expired token.
- 403 - Not allowed for the role or the token.
- 404 - Not found.
- 405 - Method not allowed.
- 409 - Conflict.
- 429 - Too many requests.
Retry-Afteris the seconds to wait. - 500 - Internal server error.