My Apps

    OAuth 2.0 without SDKs

    OAuth 2.0 without SDKs

    If you are not ready to use any of the official Box SDKs, or an SDK is not available in your language of choice, it is totally possible to use the Box APIs without them.

    To authenticate a user using OAuth 2.0. the user is redirected to the Box web app in a browser where they log in and grant 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 authorization URL
    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.

    It is possible to act as another user using the As-User header.

    Prerequisites

    Before continuing you will need to have completed the following steps.

    • Create a Box Application within the developer console with the OAuth 2.0 authentication method.
    • Copy the client_id and client_secret values and keep them handy.

    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 authorization URL

    The first step is to configure the authorization URL of your application.

    .Net
    var baseUrl = "https://account.box.com/api/oauth2/authorize";
    var clientId = "[CLIENT_ID]";
    var authorizationUrl = $"{baseUrl}?client_id={clientId}&response_type=code";
    Java
    String baseUrl = "https://account.box.com/api/oauth2/authorize";
    String clientId = "[CLIENT_ID]";
    String authorizationUrl = String.format("%s?client_id=%s&response_type=code", baseUrl, clientId);
    Python
    base_url = 'https://account.box.com/api/oauth2/authorize'
    client_id = '[CLIENT_ID]';
    authorizationUrl = f'{base_url}?client_id=${client_id}&response_type=code'
    Node
    var baseUrl = "https://account.box.com/api/oauth2/authorize";
    var clientId = "[CLIENT_ID]";
    var authorizationUrl = `${baseUrl}?client_id=${clientId}&response_type=code`;

    2. Redirect user

    Next, redirect the user to the authorization 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.

    .NET
    var authorizationUrl = $"{baseUrl}?client_id={clientId}&response_type=code";
    // redirectTo(authorizationUrl);
    Java
    String authorizationUrl = String.format("%s?client_id=%s&response_type=code", baseUrl, clientId);
    
    // response.redirect(authorizationUrl);
    Python
    auth_url = f'{base_url}?client_id=${client_id}&response_type=code'
    // redirect(auth_url, code=302)
    Node
    var authorizationUrl = `${baseUrl}?client_id=${clientId}&response_type=code`;
    // res.redirect(authorize_url)

    Additionalquery 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
    using System.Net;
    using System.Net.Http;
    using Newtonsoft.Json;
    
    String authenticationUrl = "https://api.box.com/oauth2/token";
    var client = new HttpClient();
    
    var content = new FormUrlEncodedContent(new[]
    {
      new KeyValuePair<string, string>("grant_type", "authorization_code"),
      new KeyValuePair<string, string>("code", "[CODE]"),
      new KeyValuePair<string, string>("client_id", "[CLIENT_ID]"),
      new KeyValuePair<string, string>("client_secret", "[CLIENT_SECRET]")
    });
    
    var response = client.PostAsync(authenticationUrl, content).Result;
    
    class Token
    {
      public string access_token { get; set; }
    }
    
    var data = response.Content.ReadAsStringAsync().Result;
    var token = JsonConvert.DeserializeObject<Token>(data);
    var accessToken = token.access_token;
    Java
    String authenticationUrl = "https://api.box.com/oauth2/token";
    
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    
    params.add(new BasicNameValuePair("grant_type", "authorization_code"));
    params.add(new BasicNameValuePair("code", "[CODE]"));
    params.add(new BasicNameValuePair("client_id", "[CLIENT_ID]"));
    params.add(new BasicNameValuePair("client_secret", "[CLIENT_SECRET]"));
    
    CloseableHttpClient httpClient = HttpClientBuilder.create().disableCookieManagement().build();
    
    HttpPost request = new HttpPost(authenticationUrl);
    request.setEntity(new UrlEncodedFormEntity(params));
    
    CloseableHttpResponse httpResponse = httpClient.execute(request);
    HttpEntity entity = httpResponse.getEntity();
    
    String response = EntityUtils.toString(entity);
    httpClient.close();
    
    class Token {
      String access_token;
    }
    
    Token token = (Token) gson.fromJson(response, Token.class);
    String accessToken = token.access_token;
    Python
    authentication_url = "https://api.box.com/oauth2/token";
    
    params = urlencode({
      'grant_type': 'authorization_code',
      'assertion': '[CODE]',
      'client_id': '[CLIENT_ID]',
      'client_secret': '[CLIENT_SECRET]'
    }).encode()
    
    request = Request(authentication_url, params)
    response = urlopen(request).read()
    access_token = json.loads(response)['access_token']
    Node
    let accessToken = await axios.post(
      authenticationUrl,
      querystring.stringify({
        grant_type: 'authorization_code',
        assertion: '[CODE]',
        client_id: '[CLIENT_ID]',
        client_secret: '[CLIENT_SECRET]'
      })
    )
    .then(response => response.data.access_token)

    Summary

    By now the application should be able to authorize a user using OAuth 2.0 without using any of the SDKs, by using the following steps.

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

    To learn how to use this token head over to the guide on Making API calls.