domain resource type
Namespace: microsoft.graph
Represents a domain associated with the tenant.
Use domain operations to associate domains to a tenant, verify domain ownership, and configure supported services. Verifying a domain through Microsoft Graph doesn't configure the domain for use with Office 365 services like Exchange. Fully configuring the domain to work with Microsoft 365 products might require extra steps. For more information, see Microsoft 365 admin setup.
To associate a domain with a tenant:
Associate a domain with a tenant.
Retrieve the domain verification records. Add the verification record details to the domain's zone file using the domain registrar or DNS server configuration.
Verify the ownership of the domain. This verifies the domain and sets the isVerified property to
true.Indicate the supported services you plan to use with the domain.
Configure supported services by retrieving a list of records needed to enable services for the domain. Add the configuration record details to the domain's zone file using the domain registrar or DNS server configuration.
Methods
| Method | Return Type | Description |
|---|---|---|
| List | domain | Retrieve all domains linked to the tenant. |
| Create | domain | Adds a domain to the tenant. |
| Get | domain | Read properties and relationships of a domain object. |
| Get root domain | domain | Get the root domain of a subdomain. |
| Update | domain | Updates a domain. |
| Delete | None | Deletes a domain. |
| Force delete | None | Deletes a domain using an asynchronous operation. |
| Verify | domain | Validates the ownership of the domain. |
| Promote | Boolean | Promote a verified subdomain to the root domain. |
| List domain name references | directoryObject collection | Retrieve a list of directory objects with a reference to the domain. |
| List service configuration records | domainDnsRecord collection | Retrieve a list of domain DNS records for domain configuration. |
| List verification DNS records | domainDnsRecord collection | Retrieve a list of domain DNS records for domain verification. |
Properties
| Property | Type | Description |
|---|---|---|
| authenticationType | String | Indicates the configured authentication type for the domain. The value is either Managed or Federated. Managed indicates a cloud managed domain where Microsoft Entra ID performs user authentication. Federated indicates authentication is federated with an identity provider such as the tenant's on-premises Active Directory via Active Directory Federation Services. Not nullable. To update this property in delegated scenarios, the calling app must be assigned the Directory.AccessAsUser.All delegated permission. |
| availabilityStatus | String | This property is always null except when the verify action is used. When the verify action is used, a domain entity is returned in the response. The availabilityStatus property of the domain entity in the response is either AvailableImmediately or EmailVerifiedDomainTakeoverScheduled. |
| id | String | The fully qualified name of the domain. Key, immutable, not nullable, unique. |
| isAdminManaged | Boolean | The value of the property is false if the DNS record management of the domain is delegated to Microsoft 365. Otherwise, the value is true. Not nullable |
| isDefault | Boolean | true if this is the default domain that is used for user creation. There's only one default domain per company. Not nullable. |
| isInitial | Boolean | true if this is the initial domain created by Microsoft Online Services (contoso.com). There's only one initial domain per company. Not nullable |
| isRoot | Boolean | true if the domain is a verified root domain. Otherwise, false if the domain is a subdomain or unverified. Not nullable. |
| isVerified | Boolean | true if the domain completed domain ownership verification. Not nullable. |
| passwordNotificationWindowInDays | Int32 | Specifies the number of days before a user receives notification that their password expires. If the property isn't set, a default value of 14 days is used. |
| passwordValidityPeriodInDays | Int32 | Specifies the length of time that a password is valid before it must be changed. If the property isn't set, a default value of 90 days is used. |
| state | domainState | Status of asynchronous operations scheduled for the domain. |
| supportedServices | String collection | The capabilities assigned to the domain. Can include 0, 1 or more of following values: Email, Sharepoint, EmailInternalRelayOnly, OfficeCommunicationsOnline, SharePointDefaultDomain, FullRedelegation, SharePointPublic, OrgIdAuthentication, Yammer, Intune. The values that you can add or remove using the API include: Email, OfficeCommunicationsOnline, Yammer. Not nullable. |
Relationships
Relationships between a domain and other objects in the directory such as its verification records and service configuration records are exposed through navigation properties. You can read these relationships by targeting these navigation properties in your requests.
| Relationship | Type | Description |
|---|---|---|
| domainNameReferences | directoryObject collection | The objects such as users and groups that reference the domain ID. Read-only, Nullable. Doesn't support $expand. Supports $filter by the OData type of objects returned. For example, /domains/{domainId}/domainNameReferences/microsoft.graph.user and /domains/{domainId}/domainNameReferences/microsoft.graph.group. |
| federationConfiguration | internalDomainFederation | Domain settings configured by a customer when federated with Microsoft Entra ID. Doesn't support $expand. |
| rootDomain | domain | Root domain of a subdomain. Read-only, Nullable. Supports $expand. |
| serviceConfigurationRecords | domainDnsRecord collection | DNS records the customer adds to the DNS zone file of the domain before the domain can be used by Microsoft Online services. Read-only, Nullable. Doesn't support $expand. |
| verificationDnsRecords | domainDnsRecord collection | DNS records that the customer adds to the DNS zone file of the domain before the customer can complete domain ownership verification with Microsoft Entra ID. Read-only, Nullable. Doesn't support $expand. |
JSON representation
The following JSON representation shows the resource type.
{
"authenticationType": "String",
"availabilityStatus": "String",
"id": "String (identifier)",
"isAdminManaged": true,
"isDefault": true,
"isInitial": true,
"isRoot": true,
"isVerified": true,
"passwordNotificationWindowInDays": 14,
"passwordValidityPeriodInDays": 90,
"state": {"@odata.type": "microsoft.graph.domainState"},
"supportedServices": ["String"]
}