# 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](export/get-csv-file-of-export.html)) | Either an access token in the `Authorization` header or an API key in the `Api-Key` header. |
| `GET /v3/public_keys` ([Public Keys](regulation-resources/encrypted-files/public-keys.html)) | No authentication. |

The same access tokens authenticate requests to the DIDWW prices services. See
[Prices Resources](prices-resources/index.html).

---

## API keys

API keys are created and managed in the DIDWW User Panel. For creation
instructions, see [How to Get Your API Key](../configuration.html#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](https://my-sandbox.didww.com/#/api) |
| Production | `https://auth.didww.com/token` | `https://api.didww.com/v3` | [Production User Panel](https://my.didww.com/#/api) |

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](#authentication-audiences-v35) 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](#authentication-scopes-v35). |
| 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](#authentication-version-v35). |
| 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

Full Access TokenRead-only Token for Several ServicesUnknown Audience

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

---

## Use the access token

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

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

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](../api-versioning.html).

### 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](overview.html). | `api.didww.com` | `sandbox-api.didww.com` |
| `api-vin.didww.com` | [Inbound call rates](prices-resources/inbound-call-prices/index.html): 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](prices-resources/outbound-call-prices/index.html): 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](prices-resources/sms-prices/index.html): 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](prices-resources/index.html).
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](prices-resources/index.html).

| 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](export/get-csv-file-of-export.html), 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:

[[DIDWW-API-EXAMPLE-START]]

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}
```

[[DIDWW-API-EXAMPLE-END]]

---

## 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.

## Related pages

- [OpenAPI Reference](api-reference.html)
- [Getting Started](../configuration.html)
- [API Specification](../specification/index.html)
- [API Requests in Postman](../postman.html)
- [DIDWW API Sandbox](../sandbox.html)
