My Apps

    OAuth 2.0 with SDKs

    OAuth 2.0 with SDKs

    The Box SDKs have built-in support for client-side OAuth 2.0.

    In the process a user is redirected to the Box web app in a browser where they log in and authorize the application access to their data before they are redirected back to the applications redirect_url. This last step requires the application to be running on a web server somewhere accessible to the user.

    Overview

    To complete an OAuth 2.0 flow the following steps need to be completed.

    1. Configure the Box SDK
    2. Redirect the user to the Box website
    3. The user grants the application access
    4. Exchange the authorization code for an access token

    At the end of this flow, the application has an Access Token that can be used to make API calls on behalf of this user.

    The action token acquired through OAuth 2.0 is inherently tied to the user who authorized the application. Any API call made with this token will seem to come from this application, and the user needs to have access to any file or folder the application tries to access with this token.

    Parameters

    ParameterDescription
    CLIENT_IDThe client ID or API key for the application
    CLIENT_SECRETThe client secret or API secret for the application
    REDIRECT_URIThe redirect URL for your application that a user will be sent to after they have authorized the application. This can be configured in the developer console

    1. Configure SDK

    The first step is to make sure your environment has been prepared with the SDK of your choice.

    .NET
    var redirectUrl = "[REDIRECT_URI]";
    var config = new BoxConfig("[CLIENT_ID]", "[CLIENT_SECRET]", new Uri(redirectUrl));
    var sdk = new BoxClient(config);
    Java
    import com.box.sdk.BoxAPIConnection;
    
    String authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code";
    Python
    from boxsdk import OAuth2
    
    sdk = OAuth2(
        client_id='[CLIENT_ID]',
        client_secret='[CLIENT_SECRET]'
    )
    Node
    var BoxSDK = require("box-node-sdk");
    
    var sdk = new BoxSDK({
      clientID: "[CLIENT_ID]",
      clientSecret: "[CLIENT_SECRET]"
    });

    2. Redirect user

    Next, redirect the user to the authorization URL. Most of the SDKs support a simple way to get the authorization URL for an SDK client.

    .NET
    var authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code";
    // redirectTo(authorizationUrl);
    Java
    String authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code";
    
    // response.redirect(authorizationUrl);
    Python
    auth_url, csrf_token = sdk.get_authorization_url('[REDIRECT_URL]')
    
    // redirect(auth_url, code=302)
    Node
    var authorize_url = sdk.getAuthorizeURL({
      response_type: "code"
    });
    
    // res.redirect(authorize_url)

    The way in which a user is redirected to a URL depends on the application framework used. Most framework documentation provides extensive guidance on this topic.

    The redirect URL can also be created manually as follows.

    https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code

    Additional query parameters can be passed along when redirecting the user to limit down the scope, or pass along some extra state. See the reference documentation for more information.

    3. User grants application access

    Once the user is redirected to the Box web app they will have to log in. After they logged in they are presented with a screen to approve your application.

    Example OAuth 2.0 approval screen

    When the user accepts this requests and clicks the button, the browser will redirect to your application's redirect URL as configured in the developer console.

    4. Exchange code

    The user is redirected to your application's redirect URL with a query parameter containing a short-lived authorization code.

    https://your.domain.com/path?code=1234567

    This code is not an Access Token and is only valid for a few seconds. The SDKs can be used to exchange the code for an actual Access Token.

    .NET
    var session = await sdk.Auth.AuthenticateAsync("[CODE]");
    var client = new BoxClient(config, session);
    Java
    BoxAPIConnection client = new BoxAPIConnection(
      "[CLIENT_ID]",
      "[CLIENT_SECRET]",
      "[CODE]"
    );
    Python
    oauth.authenticate('[CODE]')
    client = Client(oauth)
    Node
    var code = "...";
    
    sdk.getTokensAuthorizationCodeGrant("[CODE]", null, function(err, tokenInfo) {
      var client = sdk.getPersistentClient(tokenInfo);
    });

    At the end of this flow, the application has an Access Token that can be used to make API calls on behalf of this user.