Skip to main content
is a tool that lets you build and test HTTP requests in an easy-to-use interface without configuring a full development environment. The Box Postman Collection is a set of preconfigured requests that make it possible to get started with the Box API without having to manually configure the requests.

​
Quickstart

​
Step 1: Install Postman

and install the Postman app for your operating system (Windows, Mac, or Linux). Optionally, .

​
Step 2: Configure a Box App

To use the Postman Collection, you need a Box App to authenticate with the Box API. The following examples use OAuth 2.0, but other authentication methods are available.
  1. Go to the .
  2. Either:
    • Select your application and make sure it uses Standard OAuth 2.0 as the authentication method, or
    • Select New App, then enter an App Name and select OAuth 2.0 as the App Type.
  3. In the Configuration tab, scroll to the OAuth 2.0 Redirect URIs section and set the Redirect URI to https://oauth.pstmn.io/v1/callback.
    If you are using the Postman web app rather than the desktop app, use https://oauth.pstmn.io/v1/browser-callback for all relevant instructions.
  4. Scroll to the Application Scopes section to select your desired . Your application must have at least one of the following scopes:
    • Manage users
    • Read all files and folders stored in Box
    • Read and write all files and folders in Box
  5. At the top of the page, click Save Changes.
  6. From the OAuth 2.0 Credentials section, copy the Client ID and Client Secret.

​
Step 3: Log in to Box

Use the Client ID and Client Secret from the previous step to authenticate with Box through Postman’s OAuth 2.0 flow.
  1. In Postman, create a or open an existing one.
  2. Go to the Authorization tab.
  3. Set the Type to OAuth 2.0.
  4. If you are using the Postman desktop app, select Authorize using browser.
  5. Fill in the Configure New Token fields:
FieldValue
Token NameAny name, for example Box Access Token
Grant TypeAuthorization Code
Callback URLhttps://oauth.pstmn.io/v1/callback (auto-filled when Authorize using browser is selected).
Auth URLhttps://account.box.com/api/oauth2/authorize
Access Token URLhttps://api.box.com/oauth2/token
Client IDYour app’s Client ID from the Developer Console
Client SecretYour app’s Client Secret from the Developer Console
ScopeLeave empty
StateLeave empty
Client AuthenticationSend client credentials in body
  1. Click Get New Access Token.
  2. A browser window opens where you log in to your Box account and grant the app access.
  3. Once approved, Postman receives your access token. Select Use Token.

​
Step 4: Fork the Box Postman Collection

Click the button below to fork the Box Postman Collection into your Postman workspace. It is recommended to fork (rather than copy) the collection so you receive updates when Box makes changes to it. Once imported, the collection appears in Postman’s left-hand sidebar. You can explore over 170 API endpoints organized by resource type.

​
Step 5: Configure the Box environment

The Box Postman Collection uses environment variables to authenticate API requests. Before making calls, you need to populate these variables in the Box environment that was imported with the collection.
  1. In the lefthand sidebar of Postman, select Box from the Environments dropdown.
  2. Complete the fields as follows:
VariableValue
client_idYour app’s Client ID from the Developer Console
client_secretYour app’s Client Secret from the Developer Console
grant_typeauthorization_code
  1. Click Save.
  2. Next, you need to obtain an authorization code and exchange it for an access token. To get the code, visit the following URL in your browser, replacing [CLIENT_ID] with your Client ID:
https://account.box.com/api/oauth2/authorize?response_type=code&client_id=[CLIENT_ID]&redirect_uri=https://oauth.pstmn.io/v1/callback
  1. Log in and grant access. After the redirect, copy the code parameter from the end of the URL in your browser’s address bar. The code expires after 30 seconds, so complete the next steps quickly.
  2. Back in Postman, in the Box environment, enter code as the Variable and paste the code into the Value field.
  3. Open the Authorization folder, select Refresh access token, and click Send.
  4. When successful, the response returns an access_token and refresh_token. Enter these into your Box environment.

​
Step 6: Test your Box environment

  1. In the Box Postman Collection, expand the Folders folder and select List items in folder.
  2. The folder_id defaults to 0 (the root folder). Leave it as-is or change it to a specific folder ID.
  3. Click Send.
The response Body tab displays the items in the folder.
If Postman returns an authentication error, your access token may have expired. See for details.

​
Additional information

  • Review the from the Postman team.
  • Learn how to to handle token expiration, including automatic refresh.