Discover the URL for your organization using the Web API

You can create a client for a specific Common Data Service environment and not provide the user any options about which environment they can connect with. Only valid users for that specific environment can use your client.

If you want people using your client to be able to connect to any Common Data Service environment they have access to you could prompt them to enter the URL for their environment, but this is not recommended. Each user may have access to multiple Common Data Service environments. Users may not know or remember the URL for their environment. Expecting people to enter this URL is bound to frustrate users.

Instead, your client should provide a list of each of the available environments based on the user’s credentials. If there is more than one environment available, your application should prompt the user to choose which environment they want to connect with.

With Common Data Service, server and organization allocation may change as part of datacenter management and load balancing. Therefore, a discovery service provides a way to discover which server is serving an instance at a given time.

With the Web API discovery service, you can use standard $filter and $select parameters to a Web API service request to customize the returned list of instance data.

Global discovery service

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 Discovery Service

Note

It is recommended that users switch from the legacy regional discovery service (https://disco.crm.dynamics.com) to global discovery service (https://globaldisco.crm.dynamics.com).

For Dynamics 365 US Government users, the global discovery service is available for the GCC and GCC High users, and the URL is different from the regular global discovery service URL. More information: Dynamics 365 Government URLs.

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 Common Data Service 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 Common Data Service web application by navigating to Settings > Customization > Developer Resources

Common Data Service 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/.

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

Common Data Service Web API instances of the Discovery service require authentication with OAuth access tokens.

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.

CORS support

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

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://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(<guid>)
    GET https://disco.crm.dynamics.com/api/discovery/v9.0/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/v9.0/Instances(UniqueName='myorg')/Id/$value  
    

See also

Web API Global Discovery Service sample (C#)