API reference

API keys

Create, scope and revoke API keys. Dashboard session only: a key can never mint or list keys.

4 operationsBase URL https://packetexchange.io/api/v1Postman collection

List your API keys

GET/api/v1/account/api-keys

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Active (non-revoked) keys with their prefix, scopes and last use. Never includes a secret.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
keyPrefixrequired
string · data[].keyPrefix
The first characters of the key, for recognising it. The full key is never shown again.
labelrequired
string · data[].label
scopesrequired
string[] | null · data[].scopes
null = full access; otherwise the only scopes this key may useOne of voice:send, sms:send, dialer:write, routes:read, account:read, purchases:write, offers:write, billing:write, numbers:read, numbers:write, account:write, routes:write and 5 more
environmentrequired
string · data[].environment
One of live, test
lastUsedAtrequired
string (date-time) | null · data[].lastUsedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
expiresAtrequired
string (date-time) | null · data[].expiresAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Create an API key

POST/api/v1/account/api-keys

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Returns the full key ONCE in key. Omit scopes for a full-access key; a scoped key can reach only the operations whose scope it holds. Scopes can be narrowed later but never broadened, so include everything the integration needs. A security email is sent to the account owner.

Request body (application/json)

FieldDescription

labelrequired
string
max 100 chars
scopes
string[]
One of voice:send, sms:send, dialer:write, routes:read, account:read, purchases:write, offers:write, billing:write, numbers:read, numbers:write, account:write, routes:write and 5 more
environment
string
One of live, test
expiresAt
string (date-time) | null

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
keyrequired
string · data.key
The full secret key. Returned ONCE, here; store it now.
keyPrefixrequired
string · data.keyPrefix
Same value as prefix; the name the list and update responses use.
prefixrequired
string · data.prefix
Deprecated alias of keyPrefix, kept for existing clients.
labelrequired
string · data.label
scopesrequired
string[] | null · data.scopes
One of voice:send, sms:send, dialer:write, routes:read, account:read, purchases:write, offers:write, billing:write, numbers:read, numbers:write, account:write, routes:write and 5 more
environmentrequired
string · data.environment
One of live, test
expiresAtrequired
string (date-time) | null · data.expiresAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/api-keys" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme"
}'

Session-only: run it from the dashboard.

Rename an API key or narrow its scopes

PATCH/api/v1/account/api-keys/{id}

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Scopes may only be tightened: any scope not already on the key is rejected with VALIDATION_ERROR.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

label
string
max 100 chars
scopes
string[]
One of voice:send, sms:send, dialer:write, routes:read, account:read, purchases:write, offers:write, billing:write, numbers:read, numbers:write, account:write, routes:write and 5 more

Response 200

FieldDescription

datarequired
object
Same fields as ApiKey, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/account/api-keys/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme",
  "scopes": [
    "voice:send"
  ]
}'

Session-only: run it from the dashboard.

Revoke an API key

DELETE/api/v1/account/api-keys/{id}

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Takes effect immediately; requests with the key then get 401.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
messagerequired
string · data.message

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.