Authenticating with OAuth 2.0

In order for your applications to access Shield, or act on behalf of its fans (users), they must be authenticated. Shield relies on the industry standard OAuth 2.0 protocol for granting access. Most of HTTP request call to endpoints in Shield API should carry access token in request header(see this list for the endpoints that do not require access tokens for requests). Failing to provide valid access token will get response with 401 - Unauthorized.

In OAuth 2.0, there are two tokens:

  1. Access Token: This token should be included into request header for most of HTTP request to Shield API. We are using JWT(Json Web Token) for the access token, the payload contains username, issue time, and expire time. Clients should get another access token when it is expired from either using client_credentials grant type again or using refresh_token they use password grant type to get the token. This token will expire in one hour.

  2. Refresh Token: When an access token is expired, a client can use refresh token to get another access token without asking fans/users to input their account information again. If clients got access tokens by using client_credentials grant type, they won't have refresh tokens since they can simply can another access token by client_id and client_secret. This token will never expire unless fans/users login their accounts with other devices.

Here are the steps to make valid HTTP requests to Shield API:

Without Access Token

  1. For requesting new access token, make a request to /oauth/token with POST method.
  2. There are several grant types for OAuth 2.0 and each of the grant types dedicates to specific use case. If you are fetching general data(which is not associating to any account), you can use client_credentials grant type to get an access token. Otherwise you need to use password grant type with fans/users username and password.
  3. Once you get the access token, put the access token in request header (Authorization: Bearer $ACCESS_TOKEN) and store it for future use along with the refresh token (optional).

With Access Token

  1. You can keep using same access token as long as it is not expired.
  2. If an access token is expired : (a). If you have a refresh token, use it to renew the access token with refresh_token grant type. (b). If you do not have a refresh token, use client_credentials grant type to get another access token.

Activity Diagram for OAuth 2.0

OAuth 2.0 Details

This page contains more details about OAuth 2.0 including the purpose of each grant type, the instruction how to construct requests, and what a response payload looks like

Token Free Endpoints

See the following table for the endpoints that do not require access tokens to make requests.

Endpoint Description
/oauth/token This endpoint serves for handing out the tokens
/users This endpoint is used for registering an account