Page Comparison

Tokens

There are three types of bearer tokens used by the API: Access, ID, and Refresh. The tokens are Java Web Tokens ('JWT'). By their nature, a bearer token is similar to cash money. Once a bad actor gets ahold of a bearer token, it cannot be clawed back and can be used until they expire.

It is the responsibility of the client app to store and protect the tokens.

Token Types

Tokens will grow in size over time as additional data are added to the system. Additional content and encryption contribute to the growth and variable size of tokens.

Best Practices

There is much debate surrounding OAuth 2.0 and storage of tokens. The size of the tokens and usage give clues to how a client app should handle the usage of the tokens.

The following is the recommended approach:

• Store refresh token in one of the following methods:

  • Serverside (best option)

  • In a cookie. Make sure to set HTTP-Only=true to prevent misuse.

• Store access token and id token using one of the following methods where design allows:

  • Serverside (best option)

  • Local Storage (2nd best option)

  • Session Storage (be careful because these are cleared when tabs close)

Examining Contents Of JWT Tokens

JWT tokens are encrypted JSON objects comprised of a series of fields called “claims”. In order to see the contents of a JWT, use the decoder at https://jwt.io.

See: JWT Decoding

Common Problems

The following are some of the common problems encountered in the response when requesting tokens:

HTTP/1.1 400 Bad Request
                        Content-Type: application/json;charset=UTF-8
                        {
                        "error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type|"
                        }

invalid_request

The request is missing a required parameter, includes an unsupported parameter value (other than unsupported_grant_type), or is otherwise malformed. For example, grant_type is refresh_token but refresh_token is not included.

invalid_client

Client authentication failed. For example, when the client includes client_id and client_secret in the authorization header, but there's no such client with that client_id and client_secret.

invalid_grant

Refresh token has been revoked.

Authorization code has been consumed already or does not exist.

App client doesn't have read access to all attributes in the requested scope. For example, your app requests the email scope and your app client can read the email attribute, but not email_verified.

unauthorized_client

Client is not allowed for code grant flow or for refreshing tokens.

unsupported_grant_type

Returned if grant_type is anything other than authorization_code or refresh_token or client_credentials.

Best Practices

There is much debate surrounding OAuth 2.0 and storage of tokens. The size of the tokens and usage give clues to how a client app should handle the usage of the tokens.

The following is the recommended approach:

• Store refresh token in one of the following methods:

  • Serverside (best option)

  • In a cookie. Make sure to set HTTP-Only=true to prevent misuse.

• Store access token and id token using one of the following methods where design allows:

  • Serverside (best option)

  • Local Storage (2nd best option)

  • Session Storage (be careful because these are cleared when tabs close)