OAuth 2.0 Flow

We support the Authorization Code Grant Flow, which is suitable for web applications where the client secret can be kept confidential. For public clients (e.g., single-page applications, mobile apps), consider the Implicit Grant or Authorization Code with PKCE flow.

1. Authorization Request

The user is redirected to our authorization server to grant permission to your application.

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read write&
  state=SOME_ARBITRARY_VALUE

2. Authorization Code Grant

Upon successful authorization, the user is redirected back to your redirect_uri with an authorization code.

YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=SOME_ARBITRARY_VALUE

3. Token Request

Your application exchanges the authorization code for an access token.

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=YOUR_REDIRECT_URI&
code=AUTHORIZATION_CODE

4. Accessing Protected Resources

Include the obtained access token in the Authorization header of your API requests.

Authorization: Bearer YOUR_ACCESS_TOKEN

Key Concepts

• Client ID: A unique identifier for your application.
• Client Secret: A confidential secret for your application (for confidential clients).
• Redirect URI: The URL where the user is redirected after authorization.
• Scope: Defines the level of access your application is requesting (e.g., read, write).
• Access Token: A token that grants access to protected resources for a limited time.
• Refresh Token: A token used to obtain new access tokens without requiring the user to re-authorize.

Token Types and Lifetimes

Access tokens are typically short-lived (e.g., 1 hour) to enhance security. Refresh tokens have a longer lifetime (e.g., 30 days) and can be used to obtain new access tokens.

Token Type	Default Lifetime	Purpose
Access Token	1 Hour	Accessing protected API resources.
Refresh Token	30 Days	Obtaining new access tokens.

Scopes Supported

We offer granular control over permissions through scopes:

• openid: Request an ID token (OpenID Connect).
• profile: Access basic user profile information.
• email: Access the user's email address.
• read: Read access to data.
• write: Write access to data.
• admin: Administrative privileges (requires special approval).

Token Endpoint Details

The token endpoint is used to obtain access and refresh tokens.

URL: https://auth.msdn.example.com/oauth/token

Method: POST

Request Body Parameters:

Parameter	Type	Required	Description
grant_type	String	Yes	Type of grant. Usually authorization_code.
code	String	Yes (for authorization_code)	The authorization code received from the authorization server.
client_id	String	Yes	The client identifier.
client_secret	String	Yes (for confidential clients)	The client secret.
redirect_uri	String	Yes (for authorization_code)	The redirect URI used in the authorization request.
refresh_token	String	Yes (for refresh_token grant)	The refresh token to obtain a new access token.

Response Body (Success):

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "read write"
}

Response Body (Error):

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code"
}