Skip to main content

Authentication

About authentication​

You can authenticate your request by sending a token in the Authorization header of your request and tenancy name in X-Tenant-ID header. In the following example, replace YOUR-TOKEN and YOUR-TENANCY with a reference to your information:

curl --request GET \
--url API_URL/account/me" \
--header "Authorization: Bearer YOUR-TOKEN"\
--header "X-Tenant-ID: YOUR-TENANCY"

If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a 403 Forbidden response.

Obtaining token from your Azure AD application​

Authorization code flow​

NOTE: Check the RFC spec for a detailed flow description.

Before starting the flow, generate the STATE. It is a value that can't be predicted used by the client to maintain state between the request and callback. It should also be used as a CSRF token.

  1. Request authorization code. To do that, you should redirect the user to the /oauth/authorize page with the following query parameters:
https://login.microsoftonline.com/{APP_ID}/oauth2/v2.0/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=REQUESTED_SCOPES

This page asks the user to approve the request from the app to access their account based on the scopes specified in REQUESTED_SCOPES (eg. api://{APP_ID}/default). The user is then redirected back to the specified REDIRECT_URI.

  1. With the authorization code returned from the previous request (shown as RETURNED_CODE in the following example), you can request an access_token, with any HTTP client. The following example uses Ruby's rest-client:
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI'
RestClient.post 'https://login.microsoftonline.com/{APP_ID}/oauth2/v2.0/oauth/token', parameters

Example response:

{
 "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "token_type": "bearer",
 "expires_in": 7200,
 "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
 "created_at": 1607635748
}

  1. To retrieve a new access_token, use the refresh_token parameter. Refresh tokens may be used even after the access_token itself expires. This request:

    • Invalidates the existing access_token and refresh_token.
    • Sends new tokens in the response.
parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI'
RestClient.post 'https://login.microsoftonline.com/{APP_ID}/oauth2/v2.0/oauth/token', parameters

NOTE:

The redirect_uri must match the redirect_uri used in the original authorization request.

You can now make requests to the API with the access token returned.