Authentication for API v2026-11-19#

DIDWW API v3 version 2026-11-19 authenticates requests with short-lived bearer access tokens.

Authentication takes two steps:

  1. Exchange an API key for an access token with POST /token on the DIDWW token service of your environment.

  2. Send the access token in the Authorization request header of every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

In version 2026-11-19, an API key sent in the Api-Key header is refused with 401 Unauthorized. The API key is used only to mint access tokens. The following operations are the exceptions:

Operation

Credential

POST /token on the token service

API key in the Api-Key header.

GET /v3/exports/{filename}.csv.gz (Get CSV File of Export)

Either an access token in the Authorization header or an API key in the Api-Key header.

GET /v3/public_keys (Public Keys)

No authentication.

The same access tokens authenticate requests to the DIDWW prices services. See Prices Resources.


API keys#

API keys are created and managed in the DIDWW User Panel. For creation instructions, see How to Get Your API Key.

When creating an API key, you can configure:

Setting

Description

Friendly name

A recognizable name for the API key.

Allowed IP addresses

Optional source-IP restrictions. They apply to requests made with the key (token requests and the export file download) and are copied into each access token minted with it. A change applies to tokens minted afterwards, not to tokens already issued.


Environments#

Environment

Token service

API base URL

Manage API keys

Sandbox

https://auth-sandbox.didww.com/token

https://sandbox-api.didww.com/v3

Sandbox User Panel

Production

https://auth.didww.com/token

https://api.didww.com/v3

Production User Panel

Production and Sandbox use separate accounts and API keys. Mint tokens on the token service of the environment you call, with an API key created in that environment. An access token is accepted only in the environment that minted it.


Mint an access token#

HTTP Method: POST

URL: https://auth.didww.com/token (Production), https://auth-sandbox.didww.com/token (Sandbox)

The token service uses plain JSON, not JSON:API.

Request headers#

Header

Is Required?

Description

Api-Key

Yes

API key created in the User Panel of the same environment.

Content-Type

Yes

Must be application/json.

Request body#

Name

Type

Is Required?

Description

aud

string or Array of strings

Yes

The service or services that will accept the token. Provide one audience string or an array of audience strings. Duplicates are ignored. An unknown audience rejects the whole token request. See Audiences to choose the value for your operation.

scope

string

No

full (default) or read. An empty value or null grants the default. A read: value that is not known, such as read:prices, is granted as its closest known ancestor, so compare scope in the response with the one requested. Any other value is refused. See Scopes.

api_version

string

No

Name of the API version the token selects on api.didww.com, in the YYYY-MM-DD format, for example 2026-11-19. If omitted, the default version of the account is used, or the current default version of the platform when the account has none. See Version selection.

expires_in

integer

No

Requested token lifetime in seconds. Default: 900. A value outside 60–3600 is clamped into that range, not refused.

Response attributes#

A successful request returns 200 OK with Content-Type: application/json, Cache-Control: no-store and Pragma: no-cache.

Name

Type

Description

access_token

string

The access token. Send it as Authorization: Bearer <access_token>. It is valid only in the environment that minted it.

token_type

string

Always Bearer.

expires_in

integer

Lifetime granted, in seconds, from 60 to 3600.

aud

Array of strings

The services the token was minted for.

scope

string

The scope granted: full or read. It can be wider than the one requested when a read: value was granted as its ancestor.

api_version

string

The version name the token carries: the requested one or, when api_version is omitted, the default version of the account, or the current default version of the platform when the account has none.

Examples#

http

1POST /token HTTP/1.1
2Host: auth.didww.com
3Content-Type: application/json
4Api-Key: [API key]
5
6{
7  "aud": "api.didww.com",
8  "api_version": "2026-11-19"
9}

curl

1curl -i -X POST https://auth.didww.com/token -H "Api-Key: [API key]" -H "Content-Type: application/json" --data-raw '{"api_version": "2026-11-19", "aud": "api.didww.com"}'

response

 1HTTP/1.1 200 OK
 2Content-Type: application/json
 3Cache-Control: no-store
 4Pragma: no-cache
 5
 6{
 7  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
 8  "token_type": "Bearer",
 9  "expires_in": 900,
10  "aud": [
11    "api.didww.com"
12  ],
13  "scope": "full",
14  "api_version": "2026-11-19"
15}

Use the access token#

Send the access token in the Authorization header with the Bearer prefix:

http

1GET /v3/countries HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]

curl

1curl -i -X GET https://api.didww.com/v3/countries -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"

response

 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": [
 6    {
 7      "id": "9c56fe0f-eff0-4742-85f6-24868959344a",
 8      "type": "countries",
 9      "attributes": {
10        "name": "United Kingdom",
11        "prefix": "44",
12        "iso": "GB"
13      },
14      "relationships": {
15        "regions": {
16          "links": {
17            "self": "https://api.didww.com/v3/countries/9c56fe0f-eff0-4742-85f6-24868959344a/relationships/regions",
18            "related": "https://api.didww.com/v3/countries/9c56fe0f-eff0-4742-85f6-24868959344a/regions"
19          }
20        }
21      }
22    }
23  ],
24  "meta": {
25    "api_version": "2026-11-19"
26  }
27}

Reuse the same token for every request until it expires. A token is accepted only when all of the following hold:

  • it has not expired;

  • it was minted in the environment of the API you call;

  • its aud lists the service you call;

  • the request comes from an address allowed by the IP restrictions the API key had when the token was minted;

  • its scope covers the request method.

Version selection#

For requests authenticated with an access token, the API version is selected by the token’s api_version, set when the token is minted. The X-DIDWW-API-Version request header does not select the version of a bearer request.

  • If api_version is omitted when minting, the token carries the default version of the account. For an account without a default version, it carries the current default version of the platform, which can change when a newer version is released. Minting tokens and requests with access tokens do not assign a default version to the account.

  • A well-formed version name that the API does not know selects the newest version.

  • An access token is never served a version older than 2026-11-19, the first version that accepts access tokens, nor a version older than the default version of the account.

Set api_version explicitly and check meta.api_version in the responses to confirm the version that served the request. For version policy and upgrade steps, see API Versioning and Deprecation Policy.

Scopes#

Scope

Allowed requests

full

All methods. This is the default.

read

GET and HEAD only. Any other method is refused with 403 Forbidden and WWW-Authenticate: Bearer error="insufficient_scope".

Use a read token for integrations that only read data, such as reporting or price downloads.

Audiences#

The audience (aud) attribute specifies which DIDWW services can accept your access token. Use the production host name of the service you call, even when using its sandbox host. For multiple services, provide an array of their production host names.

Audience

Use for

Production host

Sandbox host

api.didww.com

All main API resources.

api.didww.com

sandbox-api.didww.com

api-vin.didww.com

Inbound call rates: look up rates for toll-free, shared-cost and metered numbers, or download the assigned price list.

api-vin.didww.com

api-vin-sandbox.didww.com

api-vout.didww.com

Outbound call rates: look up current and scheduled rates, or download the assigned price list.

api-vout.didww.com

api-vout-sandbox.didww.com

api-sms.didww.com

SMS rates: look up inbound SMS rates and outbound A2P, P2P and OTP SMS rates, or download the assigned price lists.

api-sms.didww.com

api-sms-sandbox.didww.com

The three dedicated price services provide the price lookups, price-file downloads and file-header checks listed in Prices Resources. Configuring inbound voice trunks, outbound voice trunks and SMS trunks uses api.didww.com.

For example, creating an outbound voice trunk uses POST /v3/voice_out_trunks on api.didww.com. Looking up the outbound call rate for a destination uses GET /v3/lookup/prices on api-vout.didww.com.

Mint one token per service, or list every service you call in one token. An integration that manages outbound voice trunks and reads outbound call rates needs both api.didww.com and api-vout.didww.com in aud.

Token lifetime and renewal#

A token is valid for the expires_in seconds returned when it is minted: 900 by default, from 60 to 3600 on request. Tokens cannot be refreshed. Mint a new token before the current one expires, and keep using the current token until then instead of minting one per request.

On api.didww.com, a token is refused before it expires once the API key it was minted with is deleted, or once API access is disabled for the account.


Authentication errors#

Token service errors#

Errors from POST /token are returned as JSON objects with error and error_description, and carry Cache-Control: no-store and Pragma: no-cache.

Status code

error

Meaning

400 Bad Request

invalid_request

The body is not valid JSON, aud is missing or lists an unknown service, api_version is not a version name, or expires_in is not an integer. error_description names the parameter at fault.

400 Bad Request

invalid_scope

scope holds several values or an unknown value outside the read family.

401 Unauthorized

invalid_client

The API key is missing, unknown, disabled, belongs to another environment, or is used from an address it does not allow.

429 Too Many Requests

rate_limit_exceeded

Too many token requests from this address. The Retry-After header gives the number of seconds to wait before retrying.

API errors#

The following responses apply to api.didww.com. For the prices services, see Prices Resources.

Status code

WWW-Authenticate

Meaning

401 Unauthorized

Bearer error="invalid_token"

The access token was refused: it is malformed or expired, was minted for another audience or environment, is presented from an address outside the IP restrictions it was minted with, or the API key it was minted with has been deleted or API access is disabled for the account. The body is a JSON:API error object with code 401.

401 Unauthorized

None

The request has no access token: it sends no credentials or only an Api-Key header. The body is a JSON:API error object with code 401. Only Get CSV File of Export, which accepts an API key, answers a missing or refused API key with an empty body. An API key sent from an address outside its allowed IP addresses receives 403 Forbidden instead.

403 Forbidden

Bearer error="insufficient_scope"

The token’s scope does not cover the request method, for example a read token sending POST, PATCH or DELETE. The body is a JSON:API error object with title Insufficient scope.

403 Forbidden

None

Authentication succeeded, but the account is not allowed to perform the requested operation.

429 Too Many Requests

None

The request budget of the account for the current window is spent (too_many_requests). Retry-After gives the number of seconds to wait.

The following example shows a read token sending a write request:

http

 1PATCH /v3/dids/9df99644-f1a5-4a3c-99a4-559d758eb96b HTTP/1.1
 2Host: api.didww.com
 3Content-Type: application/vnd.api+json
 4Accept: application/vnd.api+json
 5Authorization: Bearer [access token]
 6
 7{
 8  "data": {
 9    "id": "9df99644-f1a5-4a3c-99a4-559d758eb96b",
10    "type": "dids",
11    "attributes": {
12      "description": "Support line"
13    }
14  }
15}

curl

1curl -i -X PATCH https://api.didww.com/v3/dids/9df99644-f1a5-4a3c-99a4-559d758eb96b -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"description": "Support line"}, "id": "9df99644-f1a5-4a3c-99a4-559d758eb96b", "type": "dids"}}'

response

 1HTTP/1.1 403 Forbidden
 2Content-Type: application/vnd.api+json
 3WWW-Authenticate: Bearer error="insufficient_scope"
 4
 5{
 6  "errors": [
 7    {
 8      "title": "Insufficient scope",
 9      "detail": "The token does not carry the full scope this operation requires.",
10      "code": "403",
11      "status": "403"
12    }
13  ]
14}

Security recommendations#

Keep API keys and access tokens secure and use them only from trusted server-side environments.

Recommended practices:

  • Store API keys in environment variables or a secure secrets manager.

  • Mint access tokens on your server. Do not expose API keys or access tokens in client-side code, public repositories, browser applications, mobile apps, or logs.

  • Request only the audiences and the scope the integration needs, and prefer a short lifetime.

  • Use allowed IP address restrictions where possible. They are copied into the access tokens minted with the key, so mint new tokens after changing them.

  • Use separate API keys for different applications or environments.

  • Replace API keys if they may have been exposed.

  • Remove API keys that are no longer used.