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:
Exchange an API key for an access token with
POST /tokenon the DIDWW token service of your environment.Send the access token in the
Authorizationrequest 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 |
|---|---|
|
API key in the |
|
Either an access token in the |
|
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 |
|
|
|
Production |
|
|
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 |
|---|---|---|
|
Yes |
API key created in the User Panel of the same environment. |
|
Yes |
Must be |
Request body#
Name |
Type |
Is Required? |
Description |
|---|---|---|---|
aud |
|
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 |
|
No |
|
api_version |
|
No |
Name of the API version the token selects on |
expires_in |
|
No |
Requested token lifetime in seconds. Default: |
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 |
|
The access token. Send it as |
token_type |
|
Always |
expires_in |
|
Lifetime granted, in seconds, from |
aud |
Array of |
The services the token was minted for. |
scope |
|
The scope granted: |
api_version |
|
The version name the token carries: the requested one or, when |
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}
http
1POST /token HTTP/1.1
2Host: auth.didww.com
3Content-Type: application/json
4Api-Key: [API key]
5
6{
7 "aud": [
8 "api.didww.com",
9 "api-vout.didww.com"
10 ],
11 "scope": "read",
12 "api_version": "2026-11-19",
13 "expires_in": 3600
14}
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", "api-vout.didww.com"], "expires_in": 3600, "scope": "read"}'
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": 3600,
10 "aud": [
11 "api.didww.com",
12 "api-vout.didww.com"
13 ],
14 "scope": "read",
15 "api_version": "2026-11-19"
16}
http
1POST /token HTTP/1.1
2Host: auth.didww.com
3Content-Type: application/json
4Api-Key: [API key]
5
6{
7 "aud": "example.com"
8}
curl
1curl -i -X POST https://auth.didww.com/token -H "Api-Key: [API key]" -H "Content-Type: application/json" --data-raw '{"aud": "example.com"}'
response
1HTTP/1.1 400 Bad Request
2Content-Type: application/json
3Cache-Control: no-store
4Pragma: no-cache
5
6{
7 "error": "invalid_request",
8 "error_description": "aud is not a configured audience"
9}
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
audlists 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_versionis 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 |
|---|---|
|
All methods. This is the default. |
|
|
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 |
|---|---|---|---|
|
|
|
|
|
Inbound call rates: look up rates for toll-free, shared-cost and metered numbers, or download the assigned price list. |
|
|
|
Outbound call rates: look up current and scheduled rates, or download the assigned price list. |
|
|
|
SMS rates: look up inbound SMS rates and outbound A2P, P2P and OTP SMS rates, or download the assigned price lists. |
|
|
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 |
|
Meaning |
|---|---|---|
|
|
The body is not valid JSON, |
|
|
|
|
|
The API key is missing, unknown, disabled, belongs to another environment, or is used from an address it does not allow. |
|
|
Too many token requests from this address. The |
API errors#
The following responses apply to api.didww.com. For the prices services, see
Prices Resources.
Status code |
|
Meaning |
|---|---|---|
|
|
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 |
|
None |
The request has no access token: it sends no credentials or only an
|
|
|
The token’s scope does not cover the request method, for example a
|
|
None |
Authentication succeeded, but the account is not allowed to perform the requested operation. |
|
None |
The request budget of the account for the current window is spent
( |
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.