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:
- It verifies the authenticity of the token using the public key and that the token was indeed issued to the client.
- It confirms that the user is still allowing the client to use the token. Users have the ability to revoke a previously authorized connection.
- 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 |
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.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
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.
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
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 }
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.
POST /auth/v1/token HTTP/1.1 Host: accounts.boxc.com Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= Content-Type: application/x-www-form-urlencoded sub=198210
HTTP/1.1 200 OK