> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/api-reference/account-domains.md).

# Account Domains

This document contains account domain endpoints, including parameters, requests, responses, and status codes.

## Account Domains

An account domain is a verified company email domain connected to a DocStudio account. It establishes the corporate environment in which an organization can create and manage corporate users, assign account and mailbox permissions, configure automatic mailbox creation, and apply corporate authentication rules.

The endpoints on this page manage the domain and its SAML2 or OAuth2 identity providers. They do not create users, mailboxes, roles, or permissions directly. For complete request and response schemas, parameter requirements, and status codes, use the [Swagger UI](https://api.docstudio.com/swagger-ui/index.html).

### Business goals

Account Domain endpoints support the following business goals:

* **Establish a corporate environment.** Register and verify that an organization controls a company email domain before using it for corporate user management.
* **Manage the domain lifecycle.** Retrieve, update, verify, activate, deactivate, check, or delete a domain configuration.
* **Configure corporate authentication.** Connect a SAML2 or OAuth2 identity provider to the domain and optionally require users from that domain to authenticate through SSO.
* **Automate administration.** Manage corporate domain and identity-provider configuration from an internal administration system instead of configuring it manually.

### Endpoint summary

#### Account domains

<table><thead><tr><th width="98">Method</th><th width="332">Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/account/{accountUuid}/domain</code></td><td>Retrieve account domains or find them by name or status</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/account/{accountUuid}/domain</code></td><td>Register a corporate email domain and optionally connect an identity provider</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/account/{accountUuid}/domain/{domainUuid}</code></td><td>Retrieve one domain's current configuration and status</td></tr><tr><td><code>PUT</code></td><td><code>/api/v1/account/{accountUuid}/domain/{domainUuid}</code></td><td>Change the connected identity provider or the SSO-only login setting</td></tr><tr><td><code>PATCH</code></td><td><code>/api/v1/account/{accountUuid}/domain/{domainUuid}/{action}</code></td><td>Verify, confirm, activate, deactivate, or check the domain</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/account/{accountUuid}/domain/{domainUuid}</code></td><td>Remove a domain that the organization no longer manages through the account</td></tr></tbody></table>

#### SAML2 identity providers

<table><thead><tr><th width="98">Method</th><th width="310">Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/account/{accountId}/saml-provider</code></td><td>Retrieve the SAML2 providers configured for the account</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/account/{accountId}/saml-provider</code></td><td>Add a SAML2 provider before connecting it to a corporate domain</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/account/{accountId}/saml-provider/{id}</code></td><td>Retrieve one SAML2 provider's complete configuration</td></tr><tr><td><code>PUT</code></td><td><code>/api/v1/account/{accountId}/saml-provider/{id}</code></td><td>Update SAML metadata, attribute mappings, certificates, or signing credentials</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/account/{accountId}/saml-provider/{id}</code></td><td>Remove a SAML2 provider that is no longer used</td></tr></tbody></table>

#### OAuth2 identity providers

<table><thead><tr><th width="99">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/account/{accountId}/oauth-provider</code></td><td>Retrieve the OAuth2 providers configured for the account</td></tr><tr><td><code>POST</code></td><td><code>/api/v1/account/{accountId}/oauth-provider</code></td><td>Add an OAuth2 provider before connecting it to a corporate domain</td></tr><tr><td><code>GET</code></td><td><code>/api/v1/account/{accountId}/oauth-provider/{id}</code></td><td>Retrieve one OAuth2 provider's complete configuration</td></tr><tr><td><code>PUT</code></td><td><code>/api/v1/account/{accountId}/oauth-provider/{id}</code></td><td>Update client credentials, provider endpoints, issuer information, JWK settings, or scopes</td></tr><tr><td><code>DELETE</code></td><td><code>/api/v1/account/{accountId}/oauth-provider/{id}</code></td><td>Remove an OAuth2 provider that is no longer used</td></tr></tbody></table>

### Account domain lifecycle

A domain is first registered through `POST /api/v1/account/{accountUuid}/domain`. The request can include an identity-provider UUID and the `onlySsoLogin` setting, but the identity provider must already exist in the account.

```json
{
  "ssoIdProviderUuid": "{providerUuid}",
  "onlySsoLogin": true,
  "domain": "acme.com"
}
```

Use `GET /api/v1/account/{accountUuid}/domain/{domainUuid}` to retrieve the domain before changing its configuration. The response shows its current status, verification information, connected identity provider, and `onlySsoLogin` value.

Use `PUT /api/v1/account/{accountUuid}/domain/{domainUuid}` to replace the connected identity provider or change the SSO-only login setting without recreating the domain.

```json
{
  "ssoIdProviderUuid": "{providerUuid}",
  "onlySsoLogin": true
}
```

Use one endpoint for domain verification and status changes:

```http
PATCH /api/v1/account/{accountUuid}/domain/{domainUuid}/{action}
Authorization: Bearer {token}
Content-Type: application/json

{
  "method": "DNS_TXT_RECORD"
}
```

Supported `{action}` values:

<table><thead><tr><th width="235">Action</th><th>Purpose</th></tr></thead><tbody><tr><td><code>verify</code></td><td>Start or update DNS-based domain verification</td></tr><tr><td><code>confirm</code></td><td>Confirm verification after configuring the required DNS record</td></tr><tr><td><code>activate</code></td><td>Activate the verified domain</td></tr><tr><td><code>deactivate</code></td><td>Disable the domain without deleting its configuration</td></tr><tr><td><code>check</code></td><td>Check the current verification state</td></tr></tbody></table>

Use `DNS_TXT_RECORD` or `DNS_CNAME_RECORD` as the request body `method`.

### Identity-provider configuration

SAML2 provider endpoints are intended for organizations that authenticate users through a SAML-compatible identity provider. The configuration includes SAML metadata, user attribute mappings, a signing certificate, and a signing private key.

OAuth2 provider endpoints are intended for organizations that use OAuth2 or OpenID Connect authentication. The configuration includes the client ID and secret, authorization and token endpoints, issuer URI, JWK set URI, and requested scopes.

After creating a provider, use its UUID as `ssoIdProviderUuid` when creating or updating an account domain. Set `onlySsoLogin` to `true` when users from the domain must authenticate through the connected corporate provider.

{% hint style="warning" %}
Provider configurations may contain signing private keys or OAuth2 client secrets. Store these values securely. Do not include real credentials in source code, application logs, or public documentation.
{% endhint %}

### Practical example: Configure a corporate domain with SAML2 SSO

A company uses `acme.com` email addresses and wants its corporate users to authenticate through its SAML2 identity provider. The integration must create the provider, register and verify the domain, connect the provider, and activate the domain.

#### Create the SAML2 provider

```http
POST /api/v1/account/{accountId}/saml-provider
Authorization: Bearer {token}
Content-Type: application/json

{
  "id": "68b95bf4-71a8-4fa4-b086-7fc32c187d71",
  "name": "Acme SAML",
  "firstNameMapping": "givenName",
  "lastNameMapping": "surname",
  "phoneMapping": "telephoneNumber",
  "metadataUrl": "https://idp.acme.com/saml/metadata",
  "metadataXml": "{metadataXml}",
  "signingCertificate": "{signingCertificate}",
  "signingPrivateKey": "{signingPrivateKey}"
}
```

#### Register the domain

Use the provider UUID as `ssoIdProviderUuid`. Enabling `onlySsoLogin` requires users from the domain to use the connected provider.

```http
POST /api/v1/account/{accountUuid}/domain
Authorization: Bearer {token}
Content-Type: application/json

{
  "ssoIdProviderUuid": "68b95bf4-71a8-4fa4-b086-7fc32c187d71",
  "onlySsoLogin": true,
  "domain": "acme.com"
}
```

#### Verify and activate the domain

Use the `domainUuid` returned when the domain was created. Run `verify`, `confirm`, and `activate` in that order. Configure the returned DNS record before running `confirm`.

```http
PATCH /api/v1/account/{accountUuid}/domain/{domainUuid}/{action}
Authorization: Bearer {token}
Content-Type: application/json

{
  "method": "DNS_TXT_RECORD"
}
```

Retrieve the domain to check its current configuration and status:

```http
GET /api/v1/account/{accountUuid}/domain/{domainUuid}
Authorization: Bearer {token}
```

### Practical example: Move a domain from SAML2 to OAuth2

A company already has a corporate domain but is replacing its SAML2 provider with an OAuth2 provider. The domain does not need to be recreated because its connected provider can be changed through the update endpoint.

#### Create the OAuth2 provider

```http
POST /api/v1/account/{accountId}/oauth-provider
Authorization: Bearer {token}
Content-Type: application/json

{
  "id": "c42a5f61-cecf-4ef0-b3ad-4956d3555049",
  "name": "Acme OAuth2",
  "clientId": "docstudio-client",
  "clientSecret": "{clientSecret}",
  "authorizationUri": "https://login.acme.com/oauth2/authorize",
  "tokenUri": "https://login.acme.com/oauth2/token",
  "issuerUri": "https://login.acme.com",
  "jwkSetUri": "https://login.acme.com/.well-known/jwks.json",
  "scopes": "openid profile email"
}
```

#### Connect the new provider to the domain

```http
PUT /api/v1/account/{accountUuid}/domain/{domainUuid}
Authorization: Bearer {token}
Content-Type: application/json

{
  "ssoIdProviderUuid": "c42a5f61-cecf-4ef0-b3ad-4956d3555049",
  "onlySsoLogin": true
}
```

Retrieve the domain and confirm that it references the new provider. Remove the previous SAML2 provider only after no domain uses it:

```http
GET /api/v1/account/{accountUuid}/domain/{domainUuid}
Authorization: Bearer {token}
```

```http
DELETE /api/v1/account/{accountId}/saml-provider/{id}
Authorization: Bearer {token}
```

### Related topics

* [Authorization](/api-reference/authorization.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)