Microsoft Graph Domains is the set of Microsoft Graph APIs and resources for discovering and managing your organization’s domain names in Microsoft Entra ID (Azure AD). It lets you list all domains in a tenant and read key properties (for example, whether a domain is verified, default, initial, root, or which services it supports), add new custom domains, retrieve the DNS records needed for ownership verification, and complete the verification process.
openapi: 3.1.0
info:
title: Microsoft Graph Domains
description: Needs a description.
paths:
/domains:
description: Provides operations to manage the collection of domain entities.
get:
tags:
- Domains.domain
summary: Microsoft Graph List domains
description: Retrieve a list of domain objects.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/domain-list?view=graph-rest-1.0
operationId: domains.domain.ListDomain
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.domainCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- Domains.domain
summary: Microsoft Graph Create domain
description: >-
Adds a domain to the tenant. Important: You cannot use an associated
domain with your Microsoft Entra tenant until ownership is verified. See
List verificationDnsRecords for details. Root domains require
verification. For example, contoso.com requires verification. If a root
domain is verified, subdomains of the root domain are automatically
verified. For example, subdomain.contoso.com is automatically be
verified if contoso.com has been verified.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-post-domains?view=graph-rest-1.0
operationId: domains.domain.CreateDomain
requestBody:
description: New entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domain'
required: true
responses:
2XX:
description: Created entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domain'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/domains/{domain-id}:
description: Provides operations to manage the collection of domain entities.
get:
tags:
- Domains.domain
summary: Microsoft Graph Get domain
description: Retrieve the properties and relationships of domain object.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/domain-get?view=graph-rest-1.0
operationId: domains.domain.GetDomain
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domain'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Domains.domain
summary: Microsoft Graph Update domain
description: >-
Update the properties of domain object. Only verified domains can be
updated.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-update?view=graph-rest-1.0
operationId: domains.domain.UpdateDomain
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domain'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domain'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- Domains.domain
summary: Microsoft Graph Delete domain
description: Delete a domain from a tenant.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-delete?view=graph-rest-1.0
operationId: domains.domain.DeleteDomain
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/domainNameReferences:
description: >-
Provides operations to manage the domainNameReferences property of the
microsoft.graph.domain entity.
get:
tags:
- domains.directoryObject
summary: Microsoft Graph List domainNameReferences
description: >-
Retrieve a list of directoryObject with a reference to the domain. The
returned list will contain all directory objects that have a dependency
on the domain.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-list-domainnamereferences?view=graph-rest-1.0
operationId: domains.ListDomainNameReferences
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.directoryObjectCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/domainNameReferences/{directoryObject-id}:
description: >-
Provides operations to manage the domainNameReferences property of the
microsoft.graph.domain entity.
get:
tags:
- domains.directoryObject
summary: Microsoft Graph Get domainNameReferences from domains
description: >-
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.
operationId: domains.GetDomainNameReferences
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.directoryObject'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
- name: directoryObject-id
in: path
description: The unique identifier of directoryObject
required: true
schema:
type: string
x-ms-docs-key-type: directoryObject
/domains/{domain-id}/domainNameReferences/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- domains.directoryObject
summary: Microsoft Graph Get the number of the resource
operationId: domains.domainNameReferences.GetCount-a205
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/federationConfiguration:
description: >-
Provides operations to manage the federationConfiguration property of the
microsoft.graph.domain entity.
get:
tags:
- domains.internalDomainFederation
summary: Microsoft Graph List internalDomainFederations
description: >-
Read the properties of the internalDomainFederation objects for the
domain. This API returns only one object in the collection.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-list-federationconfiguration?view=graph-rest-1.0
operationId: domains.ListFederationConfiguration
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.internalDomainFederationCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- domains.internalDomainFederation
summary: Microsoft Graph Create internalDomainFederation
description: Create a new internalDomainFederation object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-post-federationconfiguration?view=graph-rest-1.0
operationId: domains.CreateFederationConfiguration
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.internalDomainFederation'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.internalDomainFederation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/federationConfiguration/{internalDomainFederation-id}:
description: >-
Provides operations to manage the federationConfiguration property of the
microsoft.graph.domain entity.
get:
tags:
- domains.internalDomainFederation
summary: Microsoft Graph Get internalDomainFederation
description: >-
Read the properties and relationships of an internalDomainFederation
object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/internaldomainfederation-get?view=graph-rest-1.0
operationId: domains.GetFederationConfiguration
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.internalDomainFederation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- domains.internalDomainFederation
summary: Microsoft Graph Update internalDomainFederation
description: Update the properties of an internalDomainFederation object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/internaldomainfederation-update?view=graph-rest-1.0
operationId: domains.UpdateFederationConfiguration
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.internalDomainFederation'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.internalDomainFederation'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- domains.internalDomainFederation
summary: Microsoft Graph Delete internalDomainFederation
description: Delete an internalDomainFederation object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/internaldomainfederation-delete?view=graph-rest-1.0
operationId: domains.DeleteFederationConfiguration
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
- name: internalDomainFederation-id
in: path
description: The unique identifier of internalDomainFederation
required: true
schema:
type: string
x-ms-docs-key-type: internalDomainFederation
/domains/{domain-id}/federationConfiguration/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- domains.internalDomainFederation
summary: Microsoft Graph Get the number of the resource
operationId: domains.federationConfiguration.GetCount-9087
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/forceDelete:
description: Provides operations to call the forceDelete method.
post:
tags:
- domains.domain.Actions
summary: Microsoft Graph Invoke action forceDelete
description: >-
Delete a domain using an asynchronous long-running operation. Before
performing this operation, you must update or remove any references to
Exchange as the provisioning service. The following actions are
performed as part of this operation: After the domain deletion
completes, API operations for the deleted domain return an HTTP 404
status code. To verify deletion of a domain, you can perform a get
domain operation.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-forcedelete?view=graph-rest-1.0
operationId: domains.domain.forceDelete
requestBody:
description: Action parameters
content:
application/json:
schema:
type: object
properties:
disableUserAccounts:
type: boolean
default: false
nullable: true
required: true
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/promote:
description: Provides operations to call the promote method.
post:
tags:
- domains.domain.Actions
summary: Microsoft Graph Invoke action promote
description: >-
Promote a verified subdomain to the root domain. A verified domain has
its isVerified property set to true.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-promote?view=graph-rest-1.0
operationId: domains.domain.promote
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
properties:
value:
type: boolean
default: false
nullable: true
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/verify:
description: Provides operations to call the verify method.
post:
tags:
- domains.domain.Actions
summary: Microsoft Graph Invoke action verify
description: >-
Validate the ownership of a domain. This operation only applies to an
unverified domain. For an unverified domain, the isVerified property is
false.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-verify?view=graph-rest-1.0
operationId: domains.domain.verify
responses:
2XX:
description: Success
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/microsoft.graph.domain'
- type: object
nullable: true
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: action
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/rootDomain:
description: >-
Provides operations to manage the rootDomain property of the
microsoft.graph.domain entity.
get:
tags:
- Domains.domain
summary: Microsoft Graph Get rootDomain
description: Get the root domain of a subdomain. This API returns a single object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-get-rootdomain?view=graph-rest-1.0
operationId: domains.GetRootDomain
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domain'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/serviceConfigurationRecords:
description: >-
Provides operations to manage the serviceConfigurationRecords property of
the microsoft.graph.domain entity.
get:
tags:
- domains.domainDnsRecord
summary: Microsoft Graph List serviceConfigurationRecords
description: >-
Retrieves a list of domainDnsRecord objects needed to enable services
for the domain. Use the returned list to add records to the zone file of
the domain. This can be done through the domain registrar or DNS server
configuration.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/domain-list-serviceconfigurationrecords?view=graph-rest-1.0
operationId: domains.ListServiceConfigurationRecords
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.domainDnsRecordCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- domains.domainDnsRecord
summary: >-
Microsoft Graph Create new navigation property to serviceConfigurationRecords for domains
operationId: domains.CreateServiceConfigurationRecords
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domainDnsRecord'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domainDnsRecord'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
/domains/{domain-id}/serviceConfigurationRecords/{domainDnsRecord-id}:
description: >-
Provides operations to manage the serviceConfigurationRecords property of
the microsoft.graph.domain entity.
get:
tags:
- domains.domainDnsRecord
summary: Microsoft Graph Get serviceConfigurationRecords from domains
description: >-
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.
operationId: domains.GetServiceConfigurationRecords
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domainDnsRecord'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- domains.domainDnsRecord
summary: Microsoft Graph Update the navigation property serviceConfigurationRecords in domains
operationId: domains.UpdateServiceConfigurationRecords
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domainDnsRecord'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.domainDnsRecord'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- domains.domainDnsRecord
summary: Microsoft Graph Delete navigation property serviceConfigurationRecords for domains
operationId: domains.DeleteServiceConfigurationRecords
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: domain-id
in: path
description: The unique identifier of domain
required: true
schema:
type: string
x-ms-docs-key-type: domain
- name: domainDnsRecord-id
in: path
description: The unique identifier of domainDnsRecord
required: true
schema:
type: string
x-ms-docs-key-type: domainDnsRecord
/domains/{domain-id}/serviceConfigurationRecords/$cou
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/domains-openapi-original.yml