API Keys

API keys authenticate all requests to the Trunx API. Each key can be scoped to specific permissions and rate-limited independently. Keys are hashed with SHA-256 before storage — only the prefix is visible after creation.

Create API key

POST /api/keys

Creates a new API key. The full key is returned only once in the response.

The key field is shown only once at creation time. Store it securely — there is no way to retrieve the full key after this response.

Request body

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the key
`scopes`	string[]	No	Permission scopes (default: `["*"]`)
`rateLimit`	number	No	Max requests per second (default: `10`)
`expiresInDays`	number	No	Auto-expire after this many days

curl -X POST "https://api.trunx.io/api/keys" \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["sms:send", "voice:call", "dids:read"],
    "rateLimit": 20,
    "expiresInDays": 90
  }'

const res = await fetch("https://api.trunx.io/api/keys", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production API Key",
    scopes: ["sms:send", "voice:call", "dids:read"],
    rateLimit: 20,
    expiresInDays: 90,
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api.trunx.io/api/keys",
    headers={
        "Authorization": "Bearer tk_live_...",
        "Content-Type": "application/json",
    },
    json={
        "name": "Production API Key",
        "scopes": ["sms:send", "voice:call", "dids:read"],
        "rateLimit": 20,
        "expiresInDays": 90,
    },
)
data = res.json()

Response (201)

{
  "id": "key_abc123",
  "key": "tk_live_a1b2c3d4e5f6...",
  "prefix": "tk_live_a1b2",
  "name": "Production API Key",
  "scopes": ["sms:send", "voice:call", "dids:read"],
  "rateLimit": 20,
  "expiresAt": "2026-06-09T00:00:00.000Z"
}

List API keys

GET /api/keys

Returns all API keys for the authenticated account. Keys are masked — only the prefix is shown.

curl "https://api.trunx.io/api/keys" \
  -H "Authorization: Bearer tk_live_..."

const res = await fetch("https://api.trunx.io/api/keys", {
  headers: { "Authorization": "Bearer tk_live_..." },
});
const data = await res.json();

import requests

res = requests.get(
    "https://api.trunx.io/api/keys",
    headers={"Authorization": "Bearer tk_live_..."},
)
data = res.json()

Response

{
  "keys": [
    {
      "id": "key_abc123",
      "prefix": "tk_live_a1b2",
      "name": "Production API Key",
      "scopes": ["sms:send", "voice:call", "dids:read"],
      "rateLimit": 20,
      "active": true,
      "lastUsedAt": "2026-03-11T14:30:00.000Z",
      "expiresAt": "2026-06-09T00:00:00.000Z",
      "createdAt": "2026-03-11T00:00:00.000Z"
    }
  ]
}

Response fields

Field	Type	Description
`id`	string	Unique key identifier
`prefix`	string	First characters of the key (for identification)
`name`	string	Human-readable name
`scopes`	string[]	Granted permission scopes
`rateLimit`	number	Max requests per second
`active`	boolean	Whether the key is currently active
`lastUsedAt`	string \| null	ISO 8601 timestamp of last usage
`expiresAt`	string \| null	ISO 8601 expiration timestamp, or `null` if no expiry
`createdAt`	string	ISO 8601 creation timestamp

Revoke API key

DELETE /api/keys/{id}

Permanently revokes an API key. The key will immediately stop authenticating requests.

curl -X DELETE "https://api.trunx.io/api/keys/key_abc123" \
  -H "Authorization: Bearer tk_live_..."

const res = await fetch("https://api.trunx.io/api/keys/key_abc123", {
  method: "DELETE",
  headers: { "Authorization": "Bearer tk_live_..." },
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api.trunx.io/api/keys/key_abc123",
    headers={"Authorization": "Bearer tk_live_..."},
)
data = res.json()

Response

{
  "revoked": true,
  "id": "key_abc123"
}

On this page