API Keys

Manage the esms_l_ API keys used to authenticate to the Links API. See Authentication for how to use them.

Create a key

POST https://links.esmsafrica.io/v1/keys

Request body

{
  "name": "Production server",
  "environment": "live",
  "scopes": ["links:read", "links:write"]
}

Field	Type	Required	Description
`name`	string	Yes	A label for the key
`environment`	string	No	`live` (default) or `test`
`scopes`	string[]	No	Any of `links:read`, `links:write`, ``. Defaults to `[""]`.

Response - 201

{
  "id": "k1a2…",
  "name": "Production server",
  "prefix": "esms_l_ab12cd",
  "scopes": ["links:read", "links:write"],
  "environment": "live",
  "is_active": true,
  "last_used_at": null,
  "created_at": "2026-08-03T09:00:00Z",
  "key": "esms_l_ab12cd3e4f5g6h7i8j9k0l"
}

The full key is returned only once, at creation. Store it securely - it cannot be retrieved again.

Errors

Status	Description
`402`	Paid plan required, or your plan's API-key limit is reached
`422`	Invalid scope

List keys

GET https://links.esmsafrica.io/v1/keys

Returns your keys with their prefix (never the full secret) and last_used_at.

Revoke a key

DELETE https://links.esmsafrica.io/v1/keys/{id}

Immediately revokes the key. Returns 204 No Content.