Discover the URL for your organization using the Web API

  • Article

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The Discovery service for the Microsoft Dynamics 365 Web API enables your applications to determine at run-time the organizations, also known as instances, that the logged-on user belongs to. You can retrieve detailed information about those instances like the instance service URL, the Dynamics 365 release version, the instance ID and more. You can use standard $filter and $select parameters to a Web API service request to customize the returned list of instance data. The Discovery service is supported by all Dynamics 365 deployment types: Online, on-premises, and IFD.

Clients applications may need access to a Dynamics 365 instance where the instance URL may change over time. For example, when a Dynamics 365 instance is moved from one Microsoft Dynamics 365 (online) datacenter to another. The Discovery service allows clients instance to persist the instance ID or instance unique name and then use the Discovery service to look-up the current instance access URL.

In addition to datacenter specific Discovery services, that are available on the 2011 (SOAP) endpoint and through the Web API, there is also a Web API only global Discovery service that spans all operational datacenters. For more information about the Discovery service on the 2011 endpoint see Discover the URL for your organization using the Organization Service.

Information provided by the Discovery service

Organization information is stored in the Instance entity of the Discovery service. To see the kind of information contained in that entity, send an HTTP GET request to the service for one of your instances.

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

In the above example, the global Discovery service of Microsoft Dynamics 365 (online) is used to obtain the organization information of the instance with a unique name of "myorg". More details about this request is expanded upon later in this topic.

Scope of the returned information

For the global Discovery service, the Instances entity set, returns the set of instances that the user has access to across all geographies, when no filters are applied. The returned data has a scope as described below.

  • Includes all instances in the commercial cloud where the user is provisioned and enabled, except sovereign clouds instances are not returned

  • Does not include instances where the user's account is disabled

  • Does not include instances where users have been filtered out based on an instance security group

  • Does not include instances where the user has access as a result of being a delegated administrator

  • If the calling user has access to no instances, the response simply returns an empty list

How to access the Discovery services

In general, the Web API address of the Discovery service has the following format: <service base address>/api/discovery/. The addresses for each deployment type are identified below. You can easily find the Web API addresses and version number for your deployment in the Dynamics 365 web application by navigating to Settings > Customization > Developer Resources

Dynamics 365 (online) Discovery services

The service base address of the global Discovery service is : https://globaldisco.crm.dynamics.com/. This results in the service address of https://globaldisco.crm.dynamics.com/api/discovery/.

The service base address of the Discovery service for a datacenter is : https://disco.crm[N].dynamics.com/. This results in the Discovery service address of https://disco.crm[N].dynamics.com/api/discovery/. Each datacenter has an N number associated with it. For a complete list of available Microsoft Dynamics 365 (online) datacenters, and their N numbers, see Download the endpoints using the Microsoft Dynamics 365 Developer resources page.

On-premises and IFD Discovery service

The service base address of the Discovery service for an on-premises or IFD deployment is : http[s]://{servername}/ or http[s]://dev.{servername}/. This results in the service address of http[s]://{servername}/api/discovery/ or http[s]://dev.{servername}/api/discovery/.

Using the Discovery service

An entity set named Instances is used to obtain instance information. You can use $select and $filter with the Instances entity set to filter the returned data. You can also use $metadata to obtain the metadata document of the service.

Authentication

Microsoft Dynamics 365 (online) Web API instances of the Discovery service require authentication with OAuth access tokens. On-premise or IFD instances of the Discovery Web API adopt the authentication model of their deployment, supporting either Integrated Windows Authentication (IWA) or OAuth tokens from a trusted token provider. Web Application Session authentication is not supported.

When the Discovery service is configured for OAuth authentication, a request sent to the service Web API without an access token triggers a bearer challenge with the authority of the “common” endpoint and the resource ID of the service. Similarly, when an on-premise deployment is configured for OAuth, a bearer challenge returns the on-premise authority URL and the resource ID of the service.

Web API versioning

Versioning of the Discovery service for a datacenter or on-premises/IFD is supported and is consistent with version numbering as used by the Organization service . However, the global Discovery service of Microsoft Dynamics 365 (online) is not tied to the version number of the Dynamics 365 deployment. Instead, the global service uses its own version numbering. As of this writing, the global Discovery service of Microsoft Dynamics 365 (online) is at version 1.0 (v1.0). For example:

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

CORS support

The Discovery service Web API supports the CORS standard for cross-origin access as does the Organization service Web API. For more information about CORS support see Use OAuth with Cross-Origin Resource Sharing to connect a Single Page Application to Microsoft Dynamics 365.

Examples

  • Get the details of a specific instance. If you leave out the GUID, all instances that the authenticated user has access to are returned.

    GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(<guid>)
GET https://dev.crm.external.contoso.com/api/discovery/v8.1/Instances(<guid>)

  • You can use the UniqueName attribute as an alternate key.

    GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

  • Retrieve a list of available instances, filtered by production type.

    GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0

  • Retrieve a specific instance's ID property value.

    GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(UniqueName='myorg')/Id/$value

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright