Edit

domain resource type

  • Article

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. Domain operations enable registrars to automate domain association for services such as Microsoft 365. For example, as part of domain sign up, a registrar can enable a vanity domain for email, websites, authentication, etc.

To associate a domain with a tenant:

  1. Associate a domain with a tenant.

  2. Retrieve the domain verification records. Add the verification record details to the domain's zone file using the domain registrar or DNS server configuration.

  3. Verify the ownership of the domain. This will verify the domain and set the isVerified property to true.

  4. Indicate the supported services you plan to use with the domain.

  5. 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
Get domain domain Read properties and relationships of a domain object.
Create domain domain Adds a domain to the tenant.
List domain domain Retrieve all domains linked to the tenant.
List domainNameReference directoryObject collection Retrieve a list of directory objects with a reference to the domain.
List serviceConfigurationRecords domainDnsRecord collection Retrieve a list of domain DNS records for domain configuration.
List verificationDnsRecords domainDnsRecord collection Retrieve a list of domain DNS records for domain verification.
Update domain domain Updates a domain.
Delete domain None Deletes a domain.
ForceDelete domain None Deletes a domain using an asynchronous operation.
Verify domain domain Validates the ownership of the domain.
Promote domain Boolean Promote a verified subdomain to the root domain.

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 Azure AD 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.
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 has been 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 is only one default domain per company. Not nullable
isInitial Boolean true if this is the initial domain created by Microsoft Online Services (companyname.onmicrosoft.com). There is 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 has completed domain ownership verification. Not nullable
passwordNotificationWindowInDays Int32 Specifies the number of days before a user receives notification that their password will expire. If the property is not set, a default value of 14 days will be used.
passwordValidityPeriodInDays Int32 Specifies the length of time that a password is valid before it must be changed. If the property is not set, a default value of 90 days will be 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 which you can add/remove using Graph 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. Supports $expand and $filter by the OData type of objects returned. For example /domains/{domainId}/domainNameReferences/microsoft.graph.user and /domains/{domainId}/domainNameReferences/microsoft.graph.group.
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. Supports $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 Azure AD. Read-only, Nullable. Supports $expand.
federationConfiguration internalDomainFederation Domain settings configured by a customer when federated with Azure AD. Supports $expand.

JSON representation

Here is a JSON representation of the resource.

{
  "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"]
}