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.

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

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

SAML2 identity providers

Method	Endpoint	Purpose
GET	/api/v1/account/{accountId}/saml-provider	Retrieve the SAML2 providers configured for the account
POST	/api/v1/account/{accountId}/saml-provider	Add a SAML2 provider before connecting it to a corporate domain
GET	/api/v1/account/{accountId}/saml-provider/{id}	Retrieve one SAML2 provider's complete configuration
PUT	/api/v1/account/{accountId}/saml-provider/{id}	Update SAML metadata, attribute mappings, certificates, or signing credentials
DELETE	/api/v1/account/{accountId}/saml-provider/{id}	Remove a SAML2 provider that is no longer used

OAuth2 identity providers

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

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.

{
  "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.

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

Use one endpoint for domain verification and status changes:

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

{
  "method": "DNS_TXT_RECORD"
}

Supported {action} values:

Action	Purpose
verify	Start or update DNS-based domain verification
confirm	Confirm verification after configuring the required DNS record
activate	Activate the verified domain
deactivate	Disable the domain without deleting its configuration
check	Check the current verification state

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.

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.

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

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.

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.

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:

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

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

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:

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

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

Related topics

• Authorization

• Error handling and API error codes