This article will demonstrate how to create an Access Token and ID Token for an authenticated user that authorizes your application. You will need an OAuth 2.0 client before starting. See Setting up an OAuth 2.0 Client.
Authorization Endpoint
Users must authorize your client before you can receive a token. To do this you must construct a URI with several required and optional parameters that instructs the Authorization Server on how to handle the response.
| Parameter | Description | Required |
|---|---|---|
| client_id | The Client ID | Y |
| redirect_uri | The URI the user will be redirected to after accepting or declining authorization. The host name must exactly match your client's configured redirect_uri. | Y |
| response_type | The type of authorization response flow. Options: code token id_token id_token token none | Y |
| response_mode | Informs the Server of the mechanism to be used for returning parameters from the Authorization Endpoint. Default value depends on the response_type. Options: query fragment | N |
| state | Opaque value used to maintain state between the request and the callback. | N |
| nonce | Used for associating a client session with an id_token, and for mitigating replay attacks. It will be included in the id_token claims if provided. | N |
The scopes are defined in the client settings and inherited by the request. Clients that change their scopes will force users to re-authorize their application.
An example request to the Authorization Server might look like this:
GET https://accounts.boxc.com/auth/v1/authorize?client_id=10000000001663771051&response_mode=query&response_type=code&redirect_uri=https://www.myapp.com/auth?provider=boxc&state=sddb213213
The user will be prompted to sign in before consenting if they're not already signed in. If the user has previously authorized your application then it will skip the consent screen and immediately redirect the user back to the specified redirect_uri.
Response Types
The response_type instructs the Authorization Server to generate one, both, or no tokens at all. It can also affect the authorization flow by requiring an extra step. Several response types are supported and described below.
code
The "code" response type requires an additional HTTP request-response after authorization. Once the user has consented they will be redirected to your application with a code in the query parameters. This code expires after 10 minutes and is a random string that's used for retrieving the tokens:
https://www.myapp.com?state=&code=8de3a284c25392b474b453b6068e00f1e4f0b617
Your application's backend must make an additional request to the Token endpoint with this code in the request body:
POST https://accounts.boxc.com/auth/v1/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64encode({client_id}:{client_secret})
grant_type=authorization_code
code=8de3a284c25392b474b453b6068e00f1e4f0b617
redirect_uri=https://www.myapp.com/auth?provider=boxcThe "Authorization" header must be "Basic" and include the base64 encoded and concatenated Client ID and Client Secret. The redirect_uri must match what was originally sent at the start of the authorization process.
A successful response will look similar to the below:
{
"token_type": "Bearer",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFkODQ3YjJkZTNmMTY1NjFlMDg3MDJhNjY2Mjc1MWMzOGVlODc0ZjcifQ.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjkwMDEiLCJhdWQiOiIxMDAwMDAwMDAwMTY2NDM0NTY5MiIsImlhdCI6MTY2NDkxMjY1MCwiZXhwIjoxNjY1NTE3NDUwLCJlbWFpbCI6Imp1c3RpbkBib3hjLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiZmFtaWx5X25hbWUiOiJQb3BlIiwiZ2l2ZW5fbmFtZSI6Ikp1c3RpbiIsIm5hbWUiOiJKdXN0aW4gUG9wZSIsImxvY2FsZSI6ImVuIiwic3ViIjoiMSIsInpvbmVpbmZvIjoiQW1lcmljYS9OZXdfWW9yayJ9.T9C6Ik5gdVd7faTxmXy6q7s1sSnxNOVvMTXEFryii8ADFZsHL7SoDEj_9nGFrBq1mo5ra3mK9q7vr7gzk1NxJouHYjVVcO_CFKRK13Tj962_Tx7XiPlRe0eXDpIabT5HbfegI4P9ksiLBY8i79Z1PRmaTsjgy6cOJhkIz0gJOjeJmwMV6U5XwBAbFkmya6an2wujD7bJdJ7R_IZVWP8czdo779NYHhJ8cV-VdXKkpIW0HvPGBH_ZHFg3NE4TzSumdGVhohucKBCRnOoGAI5sEao0yLI01ZrsIqzdoxmWJvg75UM6JBVmvq5CGCWj0rVorSEaP639lM89W_fxrJaT3w",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFkODQ3YjJkZTNmMTY1NjFlMDg3MDJhNjY2Mjc1MWMzOGVlODc0ZjcifQ.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjkwMDEiLCJpYXQiOjE2NjQ5MTI2NTcsImV4cCI6MTk4MDI3MjY1NywiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDoxMDAwMCIsInN1YiI6IjEiLCJjbGllbnRfaWQiOiIxMDAwMDAwMDAwMTY2NDM0NTY5MiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwifQ.QyiHKRLI8J8Kmb2lR4m53BaiOJrpm1JaRUrYCnatuJbamXQKsURwyUbCD1zSYIKCLVmafmIlQFx_CwUNg7ocplQVbJ-Bg9XlY3z2WFZbdM19i1ufgtCz854sfd6dUMbmaa-DQEtBMNC6pSOtfm_SQFkIg8gHxTvlV-TjJf6HhvtcBfkZD8WAHQ1ifK2KZ4W-cPEqj_hy62rxBN_u0RrJt4AYaUEyPLI_0qt2ta3HfPBg4Ef2VoNEE1alIDoyl_Sxruk0RRNV3FUoeoaexc4dRwxEp3q-sTXhj4fA3g7qjoo5-K8mzwQAogjqmy0aDcbpyBy9B4nFU5GWT_A9-yVtZA",
"expires_in": 315360000
}The expires_in is the TTL of the Access Token.
token
The "token" response type generates just the Access Token and redirects the user to the application with the token in the URI.
id_token
The "id_token" response type generates just the ID Token and redirects the user back to the application with the token in the URI. The "openid" permission is required for ID Tokens.
GET https://accounts.boxc.com/auth/v1/authorize?client_id=10000000001663771051&response_mode=query&response_type=id_token&redirect_uri=https://www.myapp.com/auth?provider=boxc&state=sddb213213
The user will be asked to login before authorizing the client. They will then be sent to your redirect_uri by the Authorization Server with the id_token in the query like below:
GET https://www.myapp.com?state=sddb213213&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFkODQ3YjJkZTNmMTY1NjFlMDg3MDJhNjY2Mjc1MWMzOGVlODc0ZjcifQ.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjkwMDEiLCJhdWQiOiIxMDAwMDAwMDAwMTY2NDM0NTY5MiIsImlhdCI6MTY2NDkxMjY1MCwiZXhwIjoxNjY1NTE3NDUwLCJlbWFpbCI6Imp1c3RpbkBib3hjLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiZmFtaWx5X25hbWUiOiJQb3BlIiwiZ2l2ZW5fbmFtZSI6Ikp1c3RpbiIsIm5hbWUiOiJKdXN0aW4gUG9wZSIsImxvY2FsZSI6ImVuIiwic3ViIjoiMSIsInpvbmVpbmZvIjoiQW1lcmljYS9OZXdfWW9yayJ9.T9C6Ik5gdVd7faTxmXy6q7s1sSnxNOVvMTXEFryii8ADFZsHL7SoDEj_9nGFrBq1mo5ra3mK9q7vr7gzk1NxJouHYjVVcO_CFKRK13Tj962_Tx7XiPlRe0eXDpIabT5HbfegI4P9ksiLBY8i79Z1PRmaTsjgy6cOJhkIz0gJOjeJmwMV6U5XwBAbFkmya6an2wujD7bJdJ7R_IZVWP8czdo779NYHhJ8cV-VdXKkpIW0HvPGBH_ZHFg3NE4TzSumdGVhohucKBCRnOoGAI5sEao0yLI01ZrsIqzdoxmWJvg75UM6JBVmvq5CGCWj0rVorSEaP639lM89W_fxrJaT3w&token_type=Bearer&expires_in=604800
Your client must verify the signature of the JWT when decoding the token to prove it is authentic and was signed with your Private Key.
id_token token
The "id_token token" response type generates both tokens and redirects the user back to the application with the tokens in the URI similar to "id_token".
none
The "none" response type does not create tokens but it does create a user-client connection meaning users don't need to reauthorize the client next time.
Errors
You may encounter different types of errors during the Authorization process. If an error is triggered then the user will be redirected to the client's redirect_uri as long as it's valid and matches the client setting. Otherwise, the error will be displayed at the Authorization Server. For scenarios where the user is redirected an error and error_description are returned to the client in the URI as query or fragment parameters. The error_description will help you determine the problem with the authorization request.