# Domains

The `azion/domains` module is the Azion Lib library for [Domains](/en/documentation/platform/workloads/domains/). Its functions create, list, read, update, and delete the domains of your account, and each domain points to an application by its ID. The module calls Azion API v3, and every function returns a response envelope.

Install the package:

```bash
npm install azion
```

The `azion` package receives bug fixes only, and its maintenance ends in December 2026.

The samples on this page are TypeScript ES modules that use top-level `await`, and they run in Node.js. They import types with `import type`, which keeps them loadable when the type annotations are stripped.

---

## Authentication

The functions read your [personal token](/en/documentation/fundamentals/personal-tokens/) from the `AZION_TOKEN` environment variable. A client created with [createClient](#createclient) takes the token in its `token` field instead.

| Variable      | Description                       |
| ------------- | --------------------------------- |
| `AZION_TOKEN` | Your Azion personal token.        |
| `AZION_DEBUG` | With `true`, turns on debug mode. |

For how the Azion Lib packages resolve the token and the debug setting, refer to [How Azion Lib works](/en/documentation/devtools/azion-lib/how-it-works/).

---

## Response envelope

Every function returns an [AzionDomainsResponse](#aziondomainsresponse) object, `{ data?, error? }`. On success, `data` holds the domain, the list of domains, or the deleted domain. On failure, `error` holds `{ message, operation }`, where `operation` names the call that failed.

A successful [deleteDomain](#deletedomain) returns `data` too: an [AzionDeletedDomain](#aziondeleteddomain) with the `id` of the deleted domain.

---

## createClient

Creates a client that holds a token and request options and exposes the five domain functions as methods. `createClient` is also the default export of the module.

```typescript
function createClient(config?: Partial<{
  token?: string;
  options?: AzionClientOptions;
}>): AzionDomainsClient;
```

| Parameter | Type                                        | Required | Description                                      |
| --------- | ------------------------------------------- | -------- | ------------------------------------------------ |
| `token`   | `string`                                    | No       | Your Azion personal token.                       |
| `options` | [`AzionClientOptions`](#azionclientoptions) | No       | Request options for every call the client makes. |

Returns an [AzionDomainsClient](#aziondomainsclient). Its methods take the same arguments as the matching functions on this page.

This sample creates a client and a domain with it:

```typescript
import { createClient } from 'azion/domains';
import type { AzionDomain, AzionDomainsClient, AzionDomainsResponse } from 'azion/domains';

const client: AzionDomainsClient = createClient({ token: process.env.AZION_TOKEN, options: { debug: false } });

const { data: newDomain, error }: AzionDomainsResponse<AzionDomain> = await client.createDomain({ name: 'my-client-domain', edgeApplicationId: 1234567890 });
if (newDomain) {
  console.log(`Domain created with ID: ${newDomain.id} (${newDomain.url})`);
} else {
  console.error('Failed to create domain', error);
}
```

Output:

```text
Domain created with ID: 1234567891 (xxxxxxxxxx.map.azionedge.net)
```

---

## createDomain

Creates a domain that points to an application.

```typescript
function createDomain(domain: AzionCreateDomain, options?: AzionClientOptions): Promise<AzionDomainsResponse<AzionDomain>>;
```

| Parameter | Type                                        | Required | Description                                                              |
| --------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `domain`  | [`AzionCreateDomain`](#azioncreatedomain)   | Yes      | The settings of the domain. `name` and `edgeApplicationId` are required. |
| `options` | [`AzionClientOptions`](#azionclientoptions) | No       | Request options.                                                         |

Returns `data` as the created [AzionDomain](#aziondomain). The domain carries the `id` the API assigned, and `url` holds the Azion address of the domain.

```typescript
import { createDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await createDomain({
  name: 'my-domain',
  edgeApplicationId: 1234567890,
});
if (domain) {
  console.log(`Domain created with ID: ${domain.id} (${domain.url})`);
} else {
  console.error('Failed to create domain', error);
}
```

Output:

```text
Domain created with ID: 1234567892 (xxxxxxxxxx.map.azionedge.net)
```

---

## getDomains

Lists the domains of the account, one page at a time.

```typescript
function getDomains(options?: AzionClientOptions, queryParams?: {
  orderBy?: 'id' | 'name';
  page?: number;
  pageSize?: number;
  sort?: 'asc' | 'desc';
}): Promise<AzionDomainsResponse<AzionDomainCollection>>;
```

| Parameter     | Type                                        | Required | Description                                                                                            |
| ------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `options`     | [`AzionClientOptions`](#azionclientoptions) | No       | Request options.                                                                                       |
| `queryParams` | `{ orderBy?, page?, pageSize?, sort? }`     | No       | Pagination. Of these keys, the function sends only `page` to the API, and every page holds 10 domains. |

Returns `data` as an [AzionDomainCollection](#aziondomaincollection): `results` holds the page, and `count` holds the number of domains in the account, not the length of the page.

```typescript
import { getDomains } from 'azion/domains';
import type { AzionDomainCollection, AzionDomainsResponse } from 'azion/domains';

const { data: domains, error }: AzionDomainsResponse<AzionDomainCollection> = await getDomains();

if (domains) {
  console.log(`Found ${domains.count} domains; this page has ${domains.results.length}`);
} else {
  console.error('Failed to list domains', error);
}
```

Output:

```text
Found 20 domains; this page has 10
```

---

## getDomain

Returns one domain by its ID.

```typescript
function getDomain(domainId: number, options?: AzionClientOptions): Promise<AzionDomainsResponse<AzionDomain>>;
```

| Parameter  | Type                                        | Required | Description           |
| ---------- | ------------------------------------------- | -------- | --------------------- |
| `domainId` | `number`                                    | Yes      | The ID of the domain. |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | No       | Request options.      |

Returns `data` as an [AzionDomain](#aziondomain).

```typescript
import { getDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 1234567892;
const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await getDomain(domainId);

if (domain) {
  console.log(`Found domain with name: ${domain.name}`);
} else {
  console.error('Failed to get domain', error);
}
```

Output:

```text
Found domain with name: my-domain
```

---

## updateDomain

Updates a domain by its ID. The function sends a `PUT` request, and every call carries `name` and `edgeApplicationId`.

```typescript
function updateDomain(domainId: number, domain: AzionUpdateDomain, options?: AzionClientOptions): Promise<AzionDomainsResponse<AzionDomain>>;
```

| Parameter  | Type                                        | Required | Description                                                              |
| ---------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `domainId` | `number`                                    | Yes      | The ID of the domain to update.                                          |
| `domain`   | [`AzionUpdateDomain`](#azionupdatedomain)   | Yes      | The settings of the domain. `name` and `edgeApplicationId` are required. |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | No       | Request options.                                                         |

Returns `data` as the updated [AzionDomain](#aziondomain).

```typescript
import { updateDomain } from 'azion/domains';
import type { AzionDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 1234567892;
const { data: domain, error }: AzionDomainsResponse<AzionDomain> = await updateDomain(domainId, {
  name: 'my-domain-updated',
  edgeApplicationId: 1234567890,
});

if (domain) {
  console.log(`Updated domain with name: ${domain.name}`);
} else {
  console.error('Failed to update domain', error);
}
```

Output:

```text
Updated domain with name: my-domain-updated
```

---

## deleteDomain

Deletes a domain by its ID.

```typescript
function deleteDomain(domainId: number, options?: AzionClientOptions): Promise<AzionDomainsResponse<AzionDeletedDomain>>;
```

| Parameter  | Type                                        | Required | Description                     |
| ---------- | ------------------------------------------- | -------- | ------------------------------- |
| `domainId` | `number`                                    | Yes      | The ID of the domain to delete. |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | No       | Request options.                |

Returns `data` as an [AzionDeletedDomain](#aziondeleteddomain) with the `id` of the deleted domain.

```typescript
import { deleteDomain } from 'azion/domains';
import type { AzionDeletedDomain, AzionDomainsResponse } from 'azion/domains';

const domainId = 1234567891;
const { data: deletedDomain, error }: AzionDomainsResponse<AzionDeletedDomain> = await deleteDomain(domainId);

if (deletedDomain) {
  console.log(`Deleted domain with ID: ${deletedDomain.id}`);
} else {
  console.error('Failed to delete domain', error);
}
```

Output:

```text
Deleted domain with ID: 1234567891
```

---

## Types

The `azion/domains` module exports these types. Import them with `import type`.

### AzionDomainsClient

The client that [createClient](#createclient) returns.

| Method         | Arguments                                                                   | Returns                                                |
| -------------- | --------------------------------------------------------------------------- | ------------------------------------------------------ |
| `createDomain` | `domain: AzionCreateDomain, options?: AzionClientOptions`                   | `Promise<AzionDomainsResponse<AzionDomain>>`           |
| `getDomains`   | `options?: AzionClientOptions, queryParams?`                                | `Promise<AzionDomainsResponse<AzionDomainCollection>>` |
| `getDomain`    | `domainId: number, options?: AzionClientOptions`                            | `Promise<AzionDomainsResponse<AzionDomain>>`           |
| `updateDomain` | `domainId: number, domain: AzionUpdateDomain, options?: AzionClientOptions` | `Promise<AzionDomainsResponse<AzionDomain>>`           |
| `deleteDomain` | `domainId: number, options?: AzionClientOptions`                            | `Promise<AzionDomainsResponse<AzionDeletedDomain>>`    |

### AzionDomainsCreateClient

The type of [createClient](#createclient).

```typescript
type AzionDomainsCreateClient = (config?: Partial<{
  token?: string;
  options?: AzionClientOptions;
}>) => AzionDomainsClient;
```

### AzionClientOptions

Request options that every function takes in `options`, and [createClient](#createclient) takes for all its calls.

| Property | Type      | Required | Description                                           |
| -------- | --------- | -------- | ----------------------------------------------------- |
| `debug`  | `boolean` | No       | Turns on debug mode.                                  |
| `force`  | `boolean` | No       | Declared by the type. No sample on this page uses it. |

### AzionDomainsResponse

The envelope every function returns. For how to read it, refer to [Response envelope](#response-envelope).

| Property | Type                                     | Required | Description                                      |
| -------- | ---------------------------------------- | -------- | ------------------------------------------------ |
| `data`   | `T`                                      | No       | The result of the call.                          |
| `error`  | `{ message: string; operation: string }` | No       | The error message and the operation that failed. |

### AzionDomain

A domain.

| Property                      | Type                                                 | Required | Description                                                                                                   |
| ----------------------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `name`                        | `string`                                             | Yes      | The name of the domain.                                                                                       |
| `state`                       | [`ResponseState`](#responsestate)                    | No       | The state of the request.                                                                                     |
| `id`                          | `number`                                             | No       | The ID of the domain.                                                                                         |
| `url`                         | `string`                                             | No       | The Azion address of the domain.                                                                              |
| `environment`                 | `string`                                             | No       | The environment of the domain, such as `production`.                                                          |
| `active`                      | `boolean`                                            | No       | Whether the domain is active.                                                                                 |
| `edgeApplicationId`           | `number`                                             | No       | The ID of the application the domain points to.                                                               |
| `cnameAccessOnly`             | `boolean`                                            | No       | With `true`, blocks access through the Azion address of the domain, so only its CNAMEs reach the application. |
| `cnames`                      | `string[]`                                           | No       | The CNAMEs of the domain.                                                                                     |
| `edgeFirewallId`              | `number`                                             | No       | The ID of the firewall of the domain. The API returns `null` when the domain has none.                        |
| `digitalCertificateId`        | `string \| number \| null`                           | No       | The ID of the digital certificate of the domain.                                                              |
| `mtls`                        | `{ verification; trustedCaCertificateId; crlList? }` | No       | The mutual TLS settings of the domain.                                                                        |
| `mtls.verification`           | `'enforce' \| 'permissive'`                          | Yes      | The verification mode of mutual TLS.                                                                          |
| `mtls.trustedCaCertificateId` | `number`                                             | Yes      | The ID of the trusted CA certificate.                                                                         |
| `mtls.crlList`                | `number[]`                                           | No       | The IDs of the certificate revocation lists.                                                                  |

### AzionCreateDomain

The settings [createDomain](#createdomain) takes: the [AzionDomain](#aziondomain) properties without `id`, `environment`, `active`, `url`, and `state`.

| Property               | Type                                                 | Required | Description                                                                                                   |
| ---------------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `name`                 | `string`                                             | Yes      | The name of the domain.                                                                                       |
| `edgeApplicationId`    | `number`                                             | Yes      | The ID of the application the domain points to.                                                               |
| `cnameAccessOnly`      | `boolean`                                            | No       | With `true`, blocks access through the Azion address of the domain, so only its CNAMEs reach the application. |
| `cnames`               | `string[]`                                           | No       | The CNAMEs of the domain.                                                                                     |
| `edgeFirewallId`       | `number`                                             | No       | The ID of the firewall of the domain.                                                                         |
| `digitalCertificateId` | `string \| number \| null`                           | No       | The ID of the digital certificate of the domain.                                                              |
| `mtls`                 | `{ verification; trustedCaCertificateId; crlList? }` | No       | The mutual TLS settings of the domain.                                                                        |

### AzionUpdateDomain

The settings [updateDomain](#updatedomain) takes: the [AzionDomain](#aziondomain) properties without `id`, `environment`, `url`, and `state`. Unlike [AzionCreateDomain](#azioncreatedomain), it takes `active`.

| Property               | Type                                                 | Required | Description                                                                                                   |
| ---------------------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `name`                 | `string`                                             | Yes      | The name of the domain.                                                                                       |
| `edgeApplicationId`    | `number`                                             | Yes      | The ID of the application the domain points to.                                                               |
| `active`               | `boolean`                                            | No       | Whether the domain is active.                                                                                 |
| `cnameAccessOnly`      | `boolean`                                            | No       | With `true`, blocks access through the Azion address of the domain, so only its CNAMEs reach the application. |
| `cnames`               | `string[]`                                           | No       | The CNAMEs of the domain.                                                                                     |
| `edgeFirewallId`       | `number`                                             | No       | The ID of the firewall of the domain.                                                                         |
| `digitalCertificateId` | `string \| number \| null`                           | No       | The ID of the digital certificate of the domain.                                                              |
| `mtls`                 | `{ verification; trustedCaCertificateId; crlList? }` | No       | The mutual TLS settings of the domain.                                                                        |

### AzionDomainCollection

A page of domains.

| Property  | Type                              | Required | Description                           |
| --------- | --------------------------------- | -------- | ------------------------------------- |
| `state`   | [`ResponseState`](#responsestate) | Yes      | The state of the request.             |
| `count`   | `number`                          | Yes      | The number of domains in the account. |
| `pages`   | `number`                          | Yes      | The number of pages.                  |
| `results` | [`AzionDomain[]`](#aziondomain)   | Yes      | The domains on the page.              |

### AzionDeletedDomain

The result of [deleteDomain](#deletedomain).

| Property | Type                              | Required | Description                   |
| -------- | --------------------------------- | -------- | ----------------------------- |
| `id`     | `number`                          | No       | The ID of the deleted domain. |
| `state`  | [`ResponseState`](#responsestate) | No       | The state of the deletion.    |

### ResponseState

The state of a request.

```typescript
type ResponseState = 'pending' | 'executed' | 'failed';
```

---

## Related resources

- [Azion Lib](/en/documentation/devtools/azion-lib.md): The libraries Azion Lib ships and the package that carries each one.
- [Client](/en/documentation/devtools/azion-lib/client.md): One client for Storage, SQL, Purge, Domains, Applications, and AI.
- [Applications](/en/documentation/devtools/azion-lib/application.md): The Azion Lib functions that create the application a domain points to.
- [Domains](/en/documentation/platform/workloads/domains.md): Azion addresses, custom domains, CNAMEs, digital certificates, and mTLS on a domain.