Discovery Service APIs in Office 365 APIs Preview

You use Discovery Service to find endpoints for services that you access in our Office 365 APIs Preview application. In this article, you’ll find reference information for the Discover Service APIs.

Last modified: July 30, 2014

Applies to: Office 365

Prerelease content Prerelease content

The features and APIs documented in this article are in preview and are subject to change. Do not use them in production.

Your feedback about these features and APIs is important. Let us know what you think. Have questions? Connect with us on StackOverflow. Tag your questions with [office365].

In this article
/FirstSignIn API
/Services API
/AllServices API
ServiceInfo schema
Authorization API
Token API
Additional resources

The Discovery Service, described in Authenticate your Office 365 APIs Preview app, uses several APIs, some for the Discovery Service itself, and others for the authorization server.

APIs for Discovery Service

APIs for the authorization server

Protocol

HTTP Navigation

Verb

GET

Parameters

scope

A space-delimited list of capability.operation tokens. This scope is in terms. Example: MyFiles.Write or Mail.Read

redirect_uri

URI to redirect to after authorization is completed. Example: https://contoso.com/continue

lcid

Optional. A decimal LCID to localize the Email HRD UI. Example: 1031

Note Note

This API intentionally doesn’t accept the user email because that might compromise the user privacy by sending the user email out of the current domain.

Response

302 Found

Location: redirect_URI

?user_email=...

&account_type=.

&authorization_service=...

&token_service=...

&scope=...

&unsupported_scope=...

&discovery_service=...

&discovery_resource=…

user_email

The email address the user entered.

account_type

1 – Microsoft account (Live)

2 – Organizational account (Office 365)

authorization_service

Endpoint URL where the client can get an authorization code.

token_service

Endpoint URL where the client can exchange an authorization code for an access token and a refresh token.

Scope, unsupported_scope

The original scope translated for the target realm. Clients only need to know Office 365 scope terms. If the target realm is Live, the original Office 365 scope is translated into Live terms. If there are scope items that cannot be translated, they are compiled into unsupported_scope without a change.

This is necessary because each authorization service understands scope only in its own terms.

Because the Office 365 authorization service doesn’t accept a scope parameter, both scope and unsupported_scope are returned empty.

discovery_service

Endpoint URL where the client can discover target services.

Note Note

All this information is static for this user account. Therefore clients should cache it, and then reuse it to avoid annoying the end-user with unnecessary UI.

discovery_resource

Resource identification of Discovery Service. It must be passed in to the token service as part of the token request for Discovery Service.

Protocol

OData

Verb

GET

Headers

Authorization

An access token obtained during the Authorization phase. Example: Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...

Accept

Optional. This header controls the format of the response payload:

For Atom: application/atom+xml

For JSON: application/json;odata=verbose

If this header is omitted, the default is Atom. Example: Accept: application/json;odata=verbose

Parameters

The following standard OData operators are optionally available:

$select

A comma-separated list of object properties. Causes the service to project only the selected properties. It is used to conserve bandwidth by not downloading properties that are not used by the app. See http://www.odata.org/docs/. Example: Capability,ServiceUri

$filter

An OData predicate that filters the original result set. It is used to conserve bandwidth by not downloading object instances that are not used by the app. See http://www.odata.org under the Documentation tab for available predicate functions.

Response

200 OK

The response body contains a list of ServiceInfo schema entries projected, filtered, and encoded according to the OData request. See the definition of the ServiceInfo schema schema.

Protocol

OData

Verb

GET

Headers

Accept

Optional. This header controls the format of the response payload:

For Atom: application/atom+xml

For JSON: application/json;odata=verbose

If this header is omitted, the default is Atom. Example: Accept: application/json;odata=verbose

Parameters

The following standard OData operators are optionally available:

$select

A comma-separated list of object properties. Causes the service to project only the selected properties. It is used to conserve bandwidth by not downloading properties that are not used by the app. See http://www.odata.org/docs/.Example: Capability,ServiceUri

$filter

An OData predicate that filters the original result set. It is used to conserve bandwidth by not downloading object instances that are not used by the app. See http://www.odata.org under the Documentation tab for available predicate functions.

Response

200 OK

The response body contains a list of ServiceInfo schema entries projected, filtered, and encoded according to the OData request. See the definition of the ServiceInfo schema schema.

The /Services API and /AllServices API APIs use ServiceInfo entries in their response body.

Property

Type

Example

Capability

String

MyFiles

ServiceId

String

ServiceName

String

O365_SHAREPOINT

ServiceEndpointUri

String

https://contoso-my.sharepoint.com/personal/alexd_contoso_com 

ServiceResourceId

String

https://contoso-my.sharepoint.com

Protocol

HTTP Navigation

Verb

GET

Parameters

response_type

"code" breaks the process into two separate steps, but allows the client to obtain a refresh token that can be used later (within a reasonable period of time) to obtain an access token without a user consent.

"token" combines the two steps into one, and returns an access token directly, but no refresh token.

Example: code

client_id

The client’s unique ID for the target realm (account type).

client_secret

The client’s secret for the target realm (account type). This parameter is always required by Live. This parameter is not allowed for native clients by OrgId.

scope

The scope for the target realm. Use the scope parameter returned from Step 1 in the "Discovery Service flow" section. This parameter is always required by Live. This parameter is not allowed by OrgId. Example: wl_skydrive

resource

The ID of the audience for which authorization is being requested. This parameter is not allowed by Live. This parameter is always required by OrgId. Example: Microsoft.SharePoint

redirect_uri

URI to redirect to after authorization is completed. Example: https://contoso.com/continue

Response

302 Found

Location: redirect_uri

?code=...

- or –

Location: redirect_uri

?token=...

Protocol

REST

Verb

POST

Parameters

Headers:

ContentType: application/x-www-form-urlencoded

Body:

The input parameters are sent as form fields: param=value&param=value&...

grant_type

The only accepted value is "authorization_code".

client_id

See the Authorization API.

client_secret

See the Authorization API.

code

The authorization code returned from the Authorization API.

redirect_uri

See the Authorization API.

Response

200 OK

{

access_token : "...",

refresh_token : "...",

}

Show:
© 2014 Microsoft