Box Getting Started: API Setup and First Request (2026)

Getting started overview

Integrating with Box for content management and collaboration involves a defined sequence of steps, from initial account setup to executing your first API call. This guide focuses on the developer workflow, detailing how to acquire necessary credentials and perform a basic file operation using the Box API. Box provides various SDKs and comprehensive documentation to facilitate this process, supporting common programming languages and API interaction methods Box developer guides.

The Box API allows programmatic access to content stored within Box, enabling developers to manage files, folders, users, and enterprise settings. Common applications include automating document workflows, integrating with business intelligence tools, or building custom applications that require secure file storage and sharing directly. This getting started guide will walk through the core requirements for making an authenticated request.

Here's a quick reference for the key steps:

Create an account and get keys

To begin using the Box API, you must first establish a Box account, which can be a free individual account with 10 GB of storage or a business account. Once registered, you will need to access the Box Developer Console to create and configure a new application. This application will represent your integration with the Box platform and is where you'll define its authentication method and permissions.

Developer Account Setup

1. Sign Up for a Box Account: If you don't already have one, sign up for a Box account. A free personal account is sufficient for initial development, though enterprise features may require a business plan.
2. Access the Developer Console: Navigate to the Box Developer Console. This is distinct from the regular Box web application and is where you manage your API-enabled applications.
3. Create a New Application: Click the "Create New App" button. You'll be prompted to choose an "App Type." For most API integrations, "Custom Skill" or "Custom App" will be appropriate, depending on your needs. For general API access to content, "Custom App" is the standard choice.

Authentication and Credential Generation

Box supports several authentication methods, including OAuth 2.0 and Server Authentication (JWT). The choice depends on your application's architecture and how users will interact with it Box authentication guides. For server-side applications that operate without direct user interaction (e.g., background services), Server Authentication with JWT is often preferred. For applications where users authorize access to their Box content, OAuth 2.0 is the standard.

OAuth 2.0 Setup (User-authenticated applications)

1. Select OAuth 2.0: In your application settings within the Developer Console, select "OAuth 2.0 with JWT" or "Standard OAuth 2.0" as the authentication method.
2. Retrieve Client ID and Client Secret: These credentials will be displayed in your app's configuration section. The Client ID is public, but the Client Secret must be kept confidential, as it is used to authenticate your application with Box's authorization server.
3. Configure Redirect URI: For "Standard OAuth 2.0," you must specify one or more "Redirect URIs." This is the URL where Box will redirect the user after they have granted (or denied) your application access, along with an authorization code.

Server Authentication (JWT) Setup (Server-side applications)

1. Select Server Authentication (with JWT): Choose this option for server-to-server communication where a Box user context is needed without explicit user login for each API call.
2. Generate Keypair: You will be prompted to generate an RSA keypair. Box will provide the public key to store internally and will expect your application to sign JWTs with the corresponding private key. Download the configuration file (typically a JSON file), which contains your Client ID, Client Secret, Enterprise ID, and the private key ID.
3. Store Private Key Securely: The private key found in the downloaded configuration file is critical for signing your JWTs. It must be stored securely and not exposed publicly Box JWT application configuration.

Setting Application Scopes

Before making API calls, define the necessary permissions (scopes) for your application. This controls what actions your application can perform (e.g., "Read and write all files and folders," "Manage users"). Grant only the minimum necessary permissions to adhere to the principle of least privilege.

Your first request

Once your application is configured and you have your credentials, you can make your first API request. This example demonstrates uploading a simple text file using cURL for Server Authentication (JWT). This process requires generating an access token from your JWT assertion.

Step 1: Obtain an Access Token

For Server Authentication, you first need to construct and sign a JWT assertion, then exchange it for an access token. The JWT payload will include claims such as iss (your client ID), sub (the enterprise ID or user ID you're acting on behalf of), aud (https://api.box.com/oauth2/token), and exp (expiration time).

For expediency, Box provides SDKs that handle the JWT assertion and token exchange automatically. If you're not using an SDK, you'll need to implement the JWT signing logic based on RFC 7519 JSON Web Token (JWT) RFC 7519.

Assuming you have obtained an access token (let's call it YOUR_ACCESS_TOKEN) with the necessary scopes, you can proceed to make an API call.

Step 2: Upload a File with cURL

This example uploads a file named hello.txt to the root folder (ID 0) of the Box account associated with your access token. Replace YOUR_ACCESS_TOKEN with the token obtained in Step 1.

# Create a dummy file to upload
echo "Hello, Box API!" > hello.txt

# Make the API request to upload the file
curl -X POST https://upload.box.com/api/2.0/files/content \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "attributes={ \"name\": \"hello.txt\", \"parent\": { \"id\": \"0\" } }" \
  -F "[email protected]"

This cURL command performs a multipart form data upload. The attributes field specifies the file's metadata (name and parent folder ID), and the file field contains the actual file content. A successful response will return JSON data describing the newly uploaded file, including its ID, name, and URL.

Using an SDK (Python Example)

Box offers SDKs that simplify authentication and API interactions significantly. Here's a Python example for uploading a file, assuming you've set up the JWT authentication through the SDK.

from boxsdk import Client, OAuth2, JWTAuth
import os

# Replace with your actual credentials from the JWT config file
# It's recommended to load these from environment variables or a config management system
CLIENT_ID = os.environ.get('BOX_CLIENT_ID')
CLIENT_SECRET = os.environ.get('BOX_CLIENT_SECRET')
ENTERPRISE_ID = os.environ.get('BOX_ENTERPRISE_ID')
JWT_KEY_ID = os.environ.get('BOX_JWT_KEY_ID')
RSA_PRIVATE_KEY_BYTES = os.environ.get('BOX_RSA_PRIVATE_KEY').encode('utf-8') # Private key from config file
RSA_PRIVATE_KEY_PASSPHRASE = os.environ.get('BOX_RSA_PASSPHRASE').encode('utf-8') # Passphrase if key is encrypted

# Configure JWT authentication
auth = JWTAuth(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
    enterprise_id=ENTERPRISE_ID,
    jwt_key_id=JWT_KEY_ID,
    rsa_private_key_data=RSA_PRIVATE_KEY_BYTES,
    rsa_private_key_passphrase=RSA_PRIVATE_KEY_PASSPHRASE,
)

# Create a Box client instance
client = Client(auth)

# The root folder ID is '0'
root_folder = client.folder(folder_id='0')

# Create a dummy file
file_name = "hello_sdk.txt"
with open(file_name, "w") as f:
    f.write("Hello from Box Python SDK!")

# Upload the file
try:
    uploaded_file = root_folder.upload(file_name)
    print(f"File '{uploaded_file.name}' uploaded with ID: {uploaded_file.id}")
except Exception as e:
    print(f"Error uploading file: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(file_name):
        os.remove(file_name)

This Python snippet initializes the Box client using JWT authentication, then uploads a local file to the root folder. The SDK abstracts away the complexities of JWT assertion, token exchange, and HTTP request construction Box Python SDK guide.

Common next steps

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

• Explore File and Folder Operations: Refer to the Box API Reference for files and folders to understand how to list, download, update, and delete content.
• User and Group Management: If your application manages users or groups within Box, explore the Users API and Groups API.
• Webhooks and Events: Implement webhooks to receive real-time notifications about changes in Box, such as new file uploads or deletions. This is crucial for building reactive applications and integrating with downstream systems Box webhooks guide.
• Error Handling: Implement robust error handling in your application to gracefully manage API rate limits, authentication failures, and other potential issues. Box API responses include specific error codes and messages Box API error handling.
• Security Best Practices: Review Box's security guidelines, especially regarding the secure storage of API keys, access tokens, and private keys.
• Advanced Features: Explore advanced features like collaborations, metadata, tasks, and comments to enrich your application's functionality.

Troubleshooting the first call

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

• Authentication Errors (401 Unauthorized):
  • Expired Token: Access tokens have a limited lifespan. Ensure you are requesting a new token or refreshing an existing one before it expires.
  • Incorrect Credentials: Double-check your Client ID, Client Secret, JWT Key ID, and private key data. Even minor typos can cause authentication to fail.
  • Invalid Scopes: Verify that your application has been granted the necessary scopes (permissions) in the Developer Console for the API call you are attempting to make.
  • Incorrect JWT Assertion: If using Server Authentication, ensure your JWT is correctly formed and signed. Pay attention to the payload claims (iss, sub, aud, exp).
• Permission Errors (403 Forbidden):
  • Insufficient Application Scopes: Your application might not have the specific permissions required for the requested action. For example, to upload a file, it needs "Write all files and folders" permission. Adjust permissions in the Developer Console.
  • User-specific Permissions: If acting on behalf of a user, that user might not have the necessary permissions on the target folder or item.
• Bad Request Errors (400 Bad Request):
  • Malformed JSON/Payload: Check the structure of your request body. Ensure it adheres to the API's expected JSON format or multipart form data structure, as shown in the cURL example.
  • Missing Required Parameters: Ensure all mandatory parameters, such as file name or parent folder ID, are included in your request.
  • Invalid Folder ID: If uploading to a specific folder, verify the folder ID is correct and exists.
• Network Issues:
  • Verify your internet connection.
  • Check if any firewall or proxy settings are blocking outgoing requests to api.box.com or upload.box.com.
• Consult Documentation and Support:
  • Refer to the Box API Error Codes for specific explanations.
  • Use debugging tools (e.g., browser developer tools, Postman, or your SDK's logging) to inspect the exact request and response.
  • The Box developer forum or support channels can provide assistance for persistent issues.