OAuth 2.0

The OAuth 2.0 flow allows users to grant clients permission to access the API with their account. A client is required to create access tokens. An access token is required to use the API. The token is like a password or key to a door and must be kept secret. You can create up to two OAuth 2.0 clients in your account. Information about creating a client and managing client settings can be found in the Support Center.

The access tokens are JSON Web Tokens (JWT) that are encoded and signed with your client's private key. When making a request to the API the following events occur:

  1. It verifies the authenticity of the token using the public key and that the token was indeed issued to the client.
  2. It confirms that the user is still allowing the client to use the token. Users have the ability to revoke a previously authorized connection.
  3. It checks that the client has permission to read or write to the resource being accessed.

For each step a different error will be returned if any of them fail.

Request Headers

This API use the "Bearer" token type and expects two additional headers for authentication similar to the below example:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFkODQ3YjJkZTNmMTY1NjFlMDg3MDJhNjY2Mjc1MWMzOGVlODc0ZjcifQ.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjkwMDEiLCJpYXQiOjE2NjUwODUwNTcsImV4cCI6MTk4MDQ0NTA1NywiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDoxMDAwMCIsInN1YiI6IjEiLCJjbGllbnRfaWQiOiIxMDAwMDAwMDAwMTY2NDM0NTY5MiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwifQ.Bw1eJoFS2uESK0IJQ2ICBn0Ksp3m0lXt53Fiy2KjoLGc97XZs0c_Y2tjvg0qaJKDegjbmGiLlsWWE5HgA04H9ZPAdzfjWHdmFTyABB4_m821UlHIXqdYgvgfu8221QPVbwwOCBRfdoM4XrvohUxqfV9ZUmyUv0xk-G8iWR9hefkYmgRMmh5SZafqljs3iWanoIRn9vL0rSehW7PL2jobf7izMtdv1N8OHF2Vdbk9IIFvuKxpfsM_C9-KAIm1vgSLaZd3bSovN1d9JN2D9ER_Y4LHctvfA1CMLtQQo3s7LanvoKV6wj8LixjQ8MT7cPeVyiyPEF46qSvbyb8tweZcAg
X-BoxC-Client-Id: 10000000001663771051

These are example values. You are given a unique Client ID when creating a new client. The access token is granted to you by the Authorization Server after an authenticated user authorizes your client. See requesting authorization from a BoxC account for more information.

Authorization Server

The entire authorization workflow occurs at https://accounts.boxc.com/ because it relies on users to authenticate before authorizing a client. The authorization server relies on the client to send the user to it with some query parameters in the URI to identify the client and authorization type.

Redirect URI

All clients must provide a redirect_uri in the client settings and when making an OAuth 2.0 request to the authorization server. The redirect URI must exactly match the client configuration. It can include query or fragment parameters.

Actions

GET https://accounts.boxc.com/auth/v1/authorize Request authorization from a user
POST https://accounts.boxc.com/auth/v1/token Get an access token and optional id_token after using the code response type or client_credentials grant type
POST https://accounts.boxc.com/auth/v1/revoke Revokes a user-client connection
GET
https://accounts.boxc.com/auth/v1/authorize
Requests a user to authenticate with BoxC and authorize your client so you can receive an access token and/or ID token. Descriptions about the different response types and modes can be found here.
client_id The Client ID. Required.
redirect_uri Where the user-agent will be returned after allowing or declining your authorization request. Required.
response_mode Tells the authentication server to use "query" or "fragment" parameters in the redirect_uri. Optional.
response_type Tells the authorization server which type of response you're expecting after authorization. Required.
request
GET https://accounts.boxc.com/auth/v1/authorize?client_id=10000000001664345692 \
&response_mode=query&response_type=code \
&redirect_uri=https://www.myapp.com?provider=boxc
response

HTTP/1.1 200 OK

{{webpage}}
POST
https://accounts.boxc.com/auth/v1/token

Submit an authorization code to complete the process for the "code" response type and receive an access token and ID token. The redirect_uri must match the one submited at the beginning of the auth request.

This endpoint uses Basic Authorization. The username is your Client ID and the password is your Client Secret.

An example of this grant type is found here.
request
POST /auth/v1/token HTTP/1.1
Host: accounts.boxc.com
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded


grant_type=authorization_code
code=8de3a284c25392b474b453b6068e00f1e4f0b617
redirect_uri=https://www.myapp.com/auth?provider=boxc
response

HTTP/1.1 200 OK

{
    "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
}

Authenticate with client credentials to receive an Access Token for the client owner's account by using the "client_credentials" grant type. This is useful for integrations that only need access to their own resources. The scope is inherited from the client settings.

This endpoint uses Basic Authorization. The username is your Client ID and the password is your Client Secret.

request
POST /auth/v1/token HTTP/1.1
Host: accounts.boxc.com
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
response

HTTP/1.1 200 OK

{
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFkODQ3YjJkZTNmMTY1NjFlMDg3MDJhNjY2Mjc1MWMzOGVlODc0ZjcifQ.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjkwMDEiLCJpYXQiOjE2NjQ5MTI2NTcsImV4cCI6MTk4MDI3MjY1NywiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDoxMDAwMCIsInN1YiI6IjEiLCJjbGllbnRfaWQiOiIxMDAwMDAwMDAwMTY2NDM0NTY5MiIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwifQ.QyiHKRLI8J8Kmb2lR4m53BaiOJrpm1JaRUrYCnatuJbamXQKsURwyUbCD1zSYIKCLVmafmIlQFx_CwUNg7ocplQVbJ-Bg9XlY3z2WFZbdM19i1ufgtCz854sfd6dUMbmaa-DQEtBMNC6pSOtfm_SQFkIg8gHxTvlV-TjJf6HhvtcBfkZD8WAHQ1ifK2KZ4W-cPEqj_hy62rxBN_u0RrJt4AYaUEyPLI_0qt2ta3HfPBg4Ef2VoNEE1alIDoyl_Sxruk0RRNV3FUoeoaexc4dRwxEp3q-sTXhj4fA3g7qjoo5-K8mzwQAogjqmy0aDcbpyBy9B4nFU5GWT_A9-yVtZA",
    "expires_in": 315360000
}
POST
https://accounts.boxc.com/auth/v1/revoke

Removes a previously authorized user-client connection. The sub in the request body matches the sub in the JWT and is the same thing as the user ID.

This endpoint uses Basic Authorization. The username is your Client ID and the password is your Client Secret.
request
POST /auth/v1/token HTTP/1.1
Host: accounts.boxc.com
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded


sub=198210
response

HTTP/1.1 200 OK