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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`keyPrefix`requireddata[].keyPrefix	string	The first characters of the key, for recognising it. The full key is never shown again.
`label`requireddata[].label	string	-
`scopes`requireddata[].scopes	string[] \| null	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
`environment`requireddata[].environment	string	-One of `live`, `test`
`lastUsedAt`requireddata[].lastUsedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`expiresAt`requireddata[].expiresAt	string (date-time) \| null	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)

Field	Type	Description
`label`required	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

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`key`requireddata.key	string	The full secret key. Returned ONCE, here; store it now.
`keyPrefix`requireddata.keyPrefix	string	Same value as `prefix`; the name the list and update responses use.
`prefix`requireddata.prefix	string	Deprecated alias of `keyPrefix`, kept for existing clients.
`label`requireddata.label	string	-
`scopes`requireddata.scopes	string[] \| null	-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`requireddata.environment	string	-One of `live`, `test`
`expiresAt`requireddata.expiresAt	string (date-time) \| null	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`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

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`message`requireddata.message	string	-

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.