Box Component

Manage files stored in Box

Component key: box

Description#

Box is a file sharing platform that allows teams to collaborate and share files with one another. The Box component allows you to create, list, fetch, move, or delete files and folders in a customer's Box account.

A common integration pattern involves listing files in a file store, and performing a series of actions on the array of files that are returned. See our looping over files quickstart for information about how to create a loop over an array of files.

Box Connections#

Box Developer Token#

A Developer Token is a short-lived (60-minute) token that you can use for testing purposes. A developer token allows you to use the Box API to access your personal Box account only.

note

When your integration is ready for production, you'll need an OAuth 2.0 connection to authenticate your customers' Box accounts. You can also do your testing with OAuth.

Input	Notes	Example
Input Developer Token string / Required	Notes A short-lived developer token for testing purposes	Example ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

Box OAuth 2.0 Connection#

This component authenticates with Box using OAuth 2.0. You will need to create a Box OAuth 2.0 app in order to authorize your integration to access your customers' Box accounts.

You can follow along with Box's OAuth 2.0 setup documentation here. Note:

Be sure to select User Authentication (OAuth 2.0) when creating a Custom App
Take note of your Client ID and Client Secret - you'll enter those in Prismatic in a moment
Under OAuth 2.0 Redirect URI, enter https://oauth2.prismatic.io/callback
Under Application Scopes, select Write all files and folders stored in Box
Leave CORS Domains blank

When you add a Box step to an integration, a Box OAuth 2.0 connection will be created for you. Enter the Client ID and Client Secret that you noted earlier. You can leave Scopes blank to use the Application Scopes that you set up previously. Or, you can pare down scopes as desired (reference Box's scopes documentation).

Input	Default	Notes
Input Authorize URL string / Required Hidden Field	Default https://account.box.com/api/oauth2/authorize	Notes The OAuth 2.0 Authorization URL for Box
Input Client ID string / Required	Default	Notes
Input Client Secret password / Required	Default	Notes
Input Scopes string	Default	Notes A space-delimited set of one or more scopes. Leave this blank to use your app's configured default scopes.
Input Token URL string / Required Hidden Field	Default https://api.box.com/oauth2/token	Notes The OAuth 2.0 Token URL for Box

Actions#

Copy Object#

Copy a Folder or File from one path to another | key: copyObject

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input From Path string / Required	Notes This represents the source files's path. Include a leading /	Example /path/to/source/file.txt
Input To Path string / Required	Notes This represents the destination files's path. Include a leading /	Example /path/to/destination/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}

Create Folder#

Create a Folder at the specified path | key: createFolder

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Output Example Payload#

{  "data": {    "id": "exampleId",    "status": "active",    "name": "Example",    "created_at": "2020-01-01T12:00:00Z",    "description": "Example description.",    "folder": "exampleFolder"  }}

Delete Object#

Delete a Folder or File at the specified path | key: deleteObject

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Download File#

Download the file at the specified path | key: downloadFile

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Output Example Payload#

{  "data": {    "type": "Buffer",    "data": [      101,      120,      97,      109,      112,      108,      101    ]  },  "contentType": "application/octet"}

Get File Download URL#

Get a URL to download the file at the specified path | key: getFileDownloadUrl

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Output Example Payload#

{  "data": "example.com/files/file.txt"}

List Folder#

List Folder contents at the specified path | key: listFolder

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input Limit string	Notes Provide an integer value for the maximum amount of items that will be returned. Provide a value from 1 to 1000.	Example 100
Input Marker string	Notes Specify the pagination token that's returned by a previous request to retrieve the next page of results	Example lslTXFcbLQKkb0vP9Kgh5hy0Y0OnC7Z9ZPHPwPmMnxSk3eiDRMkct7D8E
Input Offset string	Notes The offset of the item at which to begin the response.	Example 3
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}

Move Object#

Move a Folder or File from one path to another | key: moveObject

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input From Path string / Required	Notes This represents the source files's path. Include a leading /	Example /path/to/source/file.txt
Input To Path string / Required	Notes This represents the destination files's path. Include a leading /	Example /path/to/destination/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}

Path Details#

Get detailed information about folders/files in the specified path | key: pathDetails

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "file",      "name": "example"    }  ]}

Upload File#

Upload a file to the specified path | key: uploadFile

Input	Notes	Example
Input Connection connection / Required	Notes	Example
Input File Contents data / Required	Notes The contents to write to a file. This can be a string of text, it can be binary data (like an image or PDF) that was generated in a previous step.	Example My File Contents
Input Path string / Required	Notes This represents the files's path. Include a leading /	Example /path/to/file.txt

Output Example Payload#

{  "data": [    {      "id": "exampleId",      "type": "folder",      "name": "example"    }  ]}