# Create and manage domains with the REST API

The Domain Provisioning API is a JSON REST API for partners and server administrators. With a scoped bearer token you can check whether a domain is free, create a domain with its admin account, update limits and expiry, and delete it. Ask your server administrator for a token and the API address. Requests support idempotency keys and are audit-logged.

## How to create and manage domains with the REST API

1. Ask your server administrator for a bearer token with the scopes you need, and the API address.
2. Send each request over HTTPS with the token in the Authorization header.
3. Add an Idempotency-Key header to create requests, so a retry never creates a domain twice.
4. Read the typed error code in any failed response and handle it.

## Example

> A reseller's billing portal calls the API the moment a customer pays. It checks the domain name, creates a 50-user domain with its admin account and a storage allowance, and stores the request id for its records.

## Operations

| Operation | What it does | Scope needed |
|---|---|---|
| Check domain | Tells you whether a domain is already registered. | domain:read |
| Authenticate admin | Confirms a domain administrator's credentials. | domain:read |
| Create domain | Creates the domain and its administrator account. | domain:write |
| Update domain | Changes users allowed, storage or expiry. | domain:write |
| Delete domain | Removes the domain. | domain:delete |

## Create fields

| Field | Meaning |
|---|---|
| domain | The domain name, for example acme.in |
| adminUsername, adminPassword | The first domain administrator |
| usersAllowed | Maximum number of mailboxes |
| totalSpaceAllowedMb | Total storage for the domain, in MB |
| adminUserAllowedSpaceMb | Mailbox size for the administrator, in MB |
| expiryDate | When the domain's subscription ends |

## Good to know

- Each token carries only the scopes it was issued with. Give a portal that only creates domains no delete scope.
- Errors come back with a code, for example DOMAIN_ALREADY_REGISTERED when the domain exists.
- Every request gets a request id and is written to an audit log.

Source: https://docs.xgenplus.com/developers/domain-provisioning-api/