Box API Getting Started: Account, Keys, and First Request (2026)

Getting started overview

Integrating with the Box API enables programmatic interaction with Box's content management platform, allowing developers to automate tasks such as file uploads, folder creation, user management, and content security. The core process for getting started involves setting up a developer account, configuring an application, and obtaining the necessary credentials for authentication. Box primarily uses OAuth 2.0 for API authentication, which secures access to user data by enabling applications to obtain limited permissions without handling user credentials directly.

This guide outlines the essential steps to configure your environment and execute a foundational API call. It covers account creation, application registration, credential generation, and a practical example of making an authenticated request to list items in a folder. Adherence to these steps prepares a development environment for more complex Box API integrations, such as those detailed in the Box API reference documentation.

Before proceeding, ensure you have a Box account. A free tier is available for individuals, providing 10 GB of storage. Paid plans offer expanded features and storage for business and enterprise use cases, as described on the Box pricing page.

Create an account and get keys

To begin, you will need a Box account and access to the Box Developer Console. This console is the central hub for managing your applications and obtaining API credentials.

1. Sign up for a Box Account: If you do not already have one, sign up for a Box account. A free personal account is sufficient for initial development and testing.
2. Access the Box Developer Console: Once logged into your Box account, navigate to the Box Developer Console.
3. Create a New Application:
   • In the Developer Console, click on 'Create New App'.
   • Select an application type. For most initial integrations, 'Custom App' is appropriate. Choose 'OAuth 2.0 with JWT' or 'OAuth 2.0 with Client Credentials Grant' if your application needs to act on behalf of specific users or as a service, respectively. For a quick start with basic user interaction, 'OAuth 2.0 with OAuth 2.0 (User Authentication)' is commonly used.
   • Provide an 'App Name' that describes your application.
   • Click 'Create App'.
4. Configure your Application:
   • After creating the app, you will be directed to its configuration page.
   • Under the 'Configuration' tab, note your 'Client ID' and 'Client Secret'. These are your primary API credentials.
   • For OAuth 2.0 (User Authentication) apps, you must specify a 'Redirect URI'. This is the URL where Box will redirect the user after they grant permission to your application. For local development, http://localhost:3000 (or a similar local address) is often used.
   • Under 'Application Scopes', select the permissions your application needs. For a basic file listing, 'Read and write all files and folders' is sufficient, or more granular options like 'Read all files and folders'.
   • Save your changes.

Your first request

With your application configured and credentials obtained, you can now make your first authenticated request. This example uses the Box API to list the items in the root folder of a Box account.

Step-by-step Quick Reference

Obtaining an Access Token (OAuth 2.0 User Authentication Flow)

To make authenticated requests, you first need an access token. For applications integrating with user accounts, the OAuth 2.0 authorization code grant flow is typical:

1. Direct User to Authorization URL: Construct an authorization URL and redirect the user's browser to it. This URL will prompt the user to log into Box and grant your application permission.

   GET https://account.box.com/api/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=YOUR_OPTIONAL_STATE

2. User Authorizes and is Redirected: After the user grants permission, Box redirects them back to your YOUR_REDIRECT_URI with an authorization code and the state parameter (if provided).

   GET YOUR_REDIRECT_URI?code=YOUR_AUTHORIZATION_CODE&state=YOUR_OPTIONAL_STATE

3. Exchange Code for Access Token: Your application then makes a server-side request to Box's token endpoint to exchange this code for an access_token and refresh_token.

   POST https://api.box.com/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_AUTHORIZATION_CODE

   The response will be a JSON object containing the access_token, refresh_token, expires_in, and token_type. The access_token is what you will use for subsequent API calls.

Making Your First API Call (List Root Folder Items)

Once you have an access_token, you can use it in the Authorization header of your API requests. The following example demonstrates listing the contents of the root folder (folder ID 0):

Using cURL:

curl -i -X GET "https://api.box.com/2.0/folders/0/items" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Accept: application/json"

Replace YOUR_ACCESS_TOKEN with the token obtained in the previous step. A successful response will return a JSON object containing a list of files and folders within the root directory:

{
    "total_count": 2,
    "entries": [
        {
            "type": "folder",
            "id": "12345",
            "sequence_id": "1",
            "etag": "1",
            "name": "My Documents"
        },
        {
            "type": "file",
            "id": "67890",
            "sequence_id": "0",
            "etag": "0",
            "name": "ImportantReport.pdf"
        }
    ]
}

This response confirms successful authentication and interaction with the Box API. For more detailed information on specific endpoints and parameters, consult the Box API Resources documentation.

Common next steps

After successfully making your first API call, consider these next steps to further your integration:

• Explore Box SDKs: Box provides official SDKs for Node.js, Python, Java, .NET, iOS, and Android. Using an SDK can simplify API interactions by handling authentication, request signing, and response parsing. Refer to the Box Developer documentation for details on each SDK.
• Manage Refresh Tokens: Access tokens are short-lived. Implement logic to use the refresh_token to obtain new access tokens without requiring the user to re-authorize your application. This is critical for maintaining long-term access.
• File and Folder Management: Experiment with other core API endpoints, such as uploading files (POST /files/content), creating folders (POST /folders), and managing sharing links (PUT /files/:id or /folders/:id).
• Webhooks: Set up Box webhooks to receive real-time notifications about events, such as file uploads, deletions, or comments. This allows your application to react dynamically to changes within Box.
• User and Group Management: If your application requires managing Box users or groups, explore the relevant API endpoints for creating, updating, and deleting these entities.
• Error Handling: Implement robust error handling to gracefully manage API responses indicating issues like invalid tokens, insufficient permissions, or rate limits. The Box API error reference provides details on common error codes.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here are some troubleshooting tips:

• Invalid Access Token: Ensure your access_token is still valid and has not expired. If it has, use your refresh_token to obtain a new one, or re-authorize your application. Verify there are no leading/trailing spaces or extra characters.
• Incorrect Client ID/Secret: Double-check that the Client ID and Client Secret used in your OAuth flow exactly match those from your application's configuration in the Box Developer Console. Mismatches prevent token exchange.
• Redirect URI Mismatch: For OAuth 2.0 (User Authentication) apps, the redirect_uri parameter in your authorization request MUST precisely match one of the Redirect URIs configured in your Box application settings. Even a trailing slash difference will cause an error.
• Insufficient Scopes: Verify that your application has been granted the necessary scopes (permissions) in the Box Developer Console. For listing folder items, ensure your app has at least 'Read all files and folders' permission. If you change scopes, the user might need to re-authorize the application to activate the new permissions.
• Network Issues or Firewall: Confirm that your network environment allows outgoing HTTPS requests to api.box.com. Corporate firewalls or proxy settings can sometimes block API traffic.
• Rate Limiting: While unlikely for a first call, repeated failed attempts in a short period might trigger rate limiting. Wait a few moments before retrying. Consult the Box API rate limit documentation for details.
• Check API Reference: Refer to the Box API documentation for the specific endpoint you are calling. Pay attention to required parameters, HTTP methods, and expected request/response formats. The documentation provides example requests and responses.
• Review Box Developer Console Logs: Some issues, particularly with app authorization or configuration, may log specific errors or warnings in the Box Developer Console under your application's settings or activity logs.