API Keys

Create an API key

Creates an API key for the authenticated account. Restrict access by listing permitted IP addresses in permitted_ips.

post/v1/api-keys

Request body

labelstring required

API key label.

activeboolean

Indicates whether the API key should be activated upon creation.

restrictedboolean

Indicates whether to restrict API key access by IP address. When enabled, only requests from IP addresses listed in permitted_ips are allowed.

permitted_ipsstring[]

List of permitted IP addresses for this API key. Each must be a valid IPv4 address. Required when restricted is true.

scopes_enabledboolean

When true, scope fields below are enforced. When false (default), the key has full access. Omitted scope fields default to { allow: none }, so with scopes_enabled: true and no scopes set the key has no access.

Example request

{
  "label": "My API key",
  "active": true,
  "restricted": true,
  "permitted_ips": [
    "192.168.1.1",
    "10.0.0.1"
  ],
  "scopes_enabled": true,
  "numbers": {
    "allow": "read"
  },
  "trunks": {
    "allow": "read"
  },
  "calls": {
    "allow": "read"
  },
  "messages": {
    "allow": "read"
  },
  "recordings": {
    "allow": "read"
  },
  "campaigns": {
    "allow": "read"
  },
  "two_fa": {
    "allow": "read"
  },
  "validator": {
    "allow": "read"
  },
  "webhooks": {
    "allow": "read"
  },
  "embeddable": {
    "allow": "read"
  },
  "billing": {
    "allow": "read"
  },
  "account": {
    "allow": "read"
  },
  "subaccounts": {
    "allow": "read"
  }
}

Response

Returns the created API key.

idinteger required

API key ID.

labelstring required

API key label.

valuestring required

API key value.

activeboolean required

Indicates whether the API key is active.

restrictedboolean required

Indicates whether IP restrictions are enabled. When enabled, the API key works only from IP addresses in permitted_ips.

permitted_ipsstring[] required

List of permitted IP addresses. If restricted is false, an empty list means no IP restrictions. If restricted is true, an empty list prevents all requests.

scopes_enabledboolean required

When true, the key is restricted to the permissions defined in the scope fields below. When false, the key has full access.

last_used_atstring date-time nullable required

Timestamp of the most recent authenticated request made with this key.

created_atstring date-time required

Creation date and time in ISO 8601 format.

Example response

{
  "id": 123,
  "label": "Production API Key",
  "value": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "active": true,
  "restricted": true,
  "permitted_ips": [
    "192.168.1.1",
    "10.0.0.1"
  ],
  "scopes_enabled": true,
  "last_used_at": "2026-04-20T15:42:11Z",
  "numbers": {
    "allow": "read"
  },
  "trunks": {
    "allow": "read"
  },
  "calls": {
    "allow": "read"
  },
  "messages": {
    "allow": "read"
  },
  "recordings": {
    "allow": "read"
  },
  "campaigns": {
    "allow": "read"
  },
  "two_fa": {
    "allow": "read"
  },
  "validator": {
    "allow": "read"
  },
  "webhooks": {
    "allow": "read"
  },
  "embeddable": {
    "allow": "read"
  },
  "billing": {
    "allow": "read"
  },
  "account": {
    "allow": "read"
  },
  "subaccounts": {
    "allow": "read"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Changes

Changed in 4 of the 50 revisions of this API.4346

Jun 15, 202676b9bb35619f336See the full diff
- ▲
  removed the required property is_active from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property is_restriction from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property is_scopes_enabled from the response with the 200 status
  response-required-property-removed
- ●
  removed the request property is_active
  request-property-removed
- ●
  removed the request property is_restriction
  request-property-removed
- ●
  removed the request property is_scopes_enabled
  request-property-removed
- ○
  added the new optional request property active
  new-optional-request-property
- ○
  added the new optional request property restricted
  new-optional-request-property
- ○
  added the new optional request property scopes_enabled
  new-optional-request-property
- ○
  added the required property active to the response with the 200 status
  response-required-property-added
- ○
  added the required property restricted to the response with the 200 status
  response-required-property-added
- ○
  added the required property scopes_enabled to the response with the 200 status
  response-required-property-added
This revision also has 42 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 29, 2026d4adae930be5138See the full diff
- ▲
  the request property label became required
  request-property-became-required
- ○
  added the new optional request property account
  new-optional-request-property
- ○
  added the new optional request property billing
  new-optional-request-property
- ○
  added the new optional request property calls
  new-optional-request-property
- ○
  added the new optional request property campaigns
  new-optional-request-property
- ○
  added the new optional request property embeddable
  new-optional-request-property
- ○
  added the new optional request property is_scopes_enabled
  new-optional-request-property
- ○
  added the new optional request property messages
  new-optional-request-property
- ○
  added the new optional request property numbers
  new-optional-request-property
- ○
  added the new optional request property recordings
  new-optional-request-property
- ○
  added the new optional request property subaccounts
  new-optional-request-property
- ○
  added the new optional request property trunks
  new-optional-request-property
- ○
  added the new optional request property two_fa
  new-optional-request-property
- ○
  added the new optional request property validator
  new-optional-request-property
- ○
  added the new optional request property webhooks
  new-optional-request-property
- ○
  added the non-success response with the status 400
  response-non-success-status-added
- ○
  added the non-success response with the status 401
  response-non-success-status-added
- ○
  the response property created_at became required for the status 200
  response-property-became-required
- ○
  the response property id became required for the status 200
  response-property-became-required
- ○
  the response property is_active became required for the status 200
  response-property-became-required
- ○
  the response property is_restriction became required for the status 200
  response-property-became-required
- ○
  the response property label became required for the status 200
  response-property-became-required
- ○
  the response property permitted_ips became required for the status 200
  response-property-became-required
- ○
  the response property value became required for the status 200
  response-property-became-required
- ○
  added the required property account to the response with the 200 status
  response-required-property-added
- ○
  added the required property billing to the response with the 200 status
  response-required-property-added
- ○
  added the required property calls to the response with the 200 status
  response-required-property-added
- ○
  added the required property campaigns to the response with the 200 status
  response-required-property-added
- ○
  added the required property embeddable to the response with the 200 status
  response-required-property-added
- ○
  added the required property is_scopes_enabled to the response with the 200 status
  response-required-property-added
- ○
  added the required property last_used_at to the response with the 200 status
  response-required-property-added
- ○
  added the required property messages to the response with the 200 status
  response-required-property-added
- ○
  added the required property numbers to the response with the 200 status
  response-required-property-added
- ○
  added the required property recordings to the response with the 200 status
  response-required-property-added
- ○
  added the required property subaccounts to the response with the 200 status
  response-required-property-added
- ○
  added the required property trunks to the response with the 200 status
  response-required-property-added
- ○
  added the required property two_fa to the response with the 200 status
  response-required-property-added
- ○
  added the required property validator to the response with the 200 status
  response-required-property-added
- ○
  added the required property webhooks to the response with the 200 status
  response-required-property-added
Apr 20, 20262e48fd9894e11See the full diff
- ○
  api operation id api_keys_create was added
  api-operation-id-added
This revision also has 163 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 12, 2026fabaadf195a91See the full diff
- ○
  endpoint added
  endpoint-added

Full history