Authentication API Reference

This document details the authentication mechanisms supported by the MSDN API. Securely accessing our services is paramount, and we provide multiple robust options.

Tip: For most applications, we recommend using OAuth 2.0 with Authorization Code flow for secure and user-friendly authentication.

Authentication Methods

1. API Keys

API Keys provide a simple way to authenticate your application. They are best suited for server-to-server communication where user interaction is not required.

Obtaining an API Key

API Keys can be generated from your developer dashboard after creating an application.

Using API Keys

Include your API Key in the Authorization header of your requests:

Authorization: ApiKey YOUR_API_KEY

Key Management

Treat your API Keys like passwords. Do not embed them directly in client-side code or version control systems. Rotate your keys regularly for enhanced security.

2. OAuth 2.0

OAuth 2.0 is a more flexible and secure authorization framework, allowing users to grant your application limited access to their data without sharing their credentials.

Supported Flows

Authorization Code Grant: Recommended for web applications and mobile apps.
Client Credentials Grant: For server-to-server authentication where no user is involved.

Endpoints

Method	Endpoint	Description
GET	`/oauth2/authorize`	Initiates the authorization code grant flow. Redirects the user to login and grant permissions.
POST	`/oauth2/token`	Exchanges an authorization code or refresh token for an access token.
POST	`/oauth2/revoke`	Revokes an existing access token.

Requesting an Access Token (Authorization Code Grant)

After the user authorizes your application, they will be redirected to your specified redirect_uri with an authorization_code. You then exchange this code for an access token:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE_RECEIVED&
redirect_uri=YOUR_REGISTERED_REDIRECT_URI&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Access Token Response

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

Using Access Tokens

Include your Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Note: Access tokens have a limited lifespan. Use the refresh token to obtain new access tokens without requiring user re-authentication.

Scopes

When requesting authorization, you can specify the permissions (scopes) your application needs. Common scopes include:

read:profile - Access to basic user profile information.
write:data - Ability to create and modify data.
read:all - Read access to all available resources.

Example scope parameter for authorization request: scope=read:profile%20write:data

Security Considerations

Always use HTTPS for all API requests to ensure data is encrypted in transit.

Validate and sanitize any user input before using it in API calls.

Implement rate limiting on your API key and OAuth client to prevent abuse.