Box

Explore 6 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Box, a hire can:

• find files by the words in their name or content,
• list what's in a folder,
• read a file as text: PDFs and other documents through the text Box makes of them, Word, Excel, PowerPoint and OpenDocument files, and text files. Of large files it reads the start. Images and other files show their name, size and date only, never their content.

If you allow changes, a hire can also:

• upload text as a file. It never overwrites a file: replacing one asks a person first.
• make a shared link to a file, view only, for people in your company or for anyone, optionally ending after a number of days. This always asks a person first.
• delete a file. This always asks a person first. It goes to Box's trash.

Hires never see the sign-in. Passwords and keys written inside files are hidden from hires when they read them.

1. Make a Box appCopy Anchor Link

Straight there: the Box Developer Console.

In the Box Developer Console: Create Platform App. Choose one way to sign in:

• User Authentication (OAuth 2.0): a person signs in, and hires see what that person sees. Under Configuration, add the redirect URI Roster shows on the connection (it ends in /api/integrations/box/oauth/callback).
• Server Authentication (Client Credentials Grant): no person signs in. The app acts as your company's service account or as one user. A Box admin must authorize the app (Admin Console → Integrations → Platform Apps Manager).

Then, under Application Scopes, tick Read all files and folders stored in Box, and Write all files and folders stored in Box to allow changes. Copy the Client ID and Client Secret.

2. Connect it in RosterCopy Anchor Link

1. Open Integrations → Tools → Add a tool, search for Box and choose it.
2. How Roster signs in: OAuth 2.0 or Client Credentials Grant, as you made the app.
3. Paste the client ID and secret. For Client Credentials, choose who it acts as (the service account or one user) and give the enterprise ID (Admin Console → Account & Billing) or the user's ID.
4. What hires may do: Find and read files, or also upload, share and delete.
5. For OAuth, click Connect with Box and sign in.

Roster checks the key when you click Connect. Once it's accepted, the connection shows Connected as your Box enterprise (or the user) and the account Roster acts as. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires accessCopy Anchor Link

On the hire's Tools tab, click Give access on Box. Read only gives the reading tools; Read and write adds upload, links and delete (if the connection allows changes).

• Folders: folder IDs, the number after /folder/ in a folder's address. Files in subfolders count. Leave it empty for everything the account can see.

When it asks firstCopy Anchor Link

You can change this per hire on the hire's Tools tab, under When it asks first.

If something goes wrongCopy Anchor Link

• "Box is still making this file's text": Box prepares text for new files in the background. Ask again in a minute.
• Nothing is found with Client Credentials: the service account sees only what's shared with it. Share the folders with it, or act as a user instead.
• Links for anyone fail: your Box admin may allow only company links.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "words to look for"
    },
    "folder": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "a folder's ID, in [brackets] in list_folder and search_files"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "text"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "description": "a folder (ID); leave out for the top",
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's ID, in [brackets] in list_folder and search_files"
    }
  },
  "required": [
    "file"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "a folder's ID, in [brackets] in list_folder and search_files"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the file's name with its extension, like summary.md or rates.csv"
    },
    "text": {
      "type": "string",
      "maxLength": 1000000,
      "description": "the file's whole content, as text"
    },
    "replace": {
      "default": false,
      "description": "replace a file of the same name (asks a person first)",
      "type": "boolean"
    }
  },
  "required": [
    "folder",
    "name",
    "text"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's ID, in [brackets] in list_folder and search_files"
    },
    "audience": {
      "default": "organization",
      "description": "anyone with the link, or only people signed in to the organisation",
      "type": "string",
      "enum": [
        "organization",
        "anyone"
      ]
    },
    "expires_in_days": {
      "description": "when the link stops working, if the service supports it",
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    }
  },
  "required": [
    "file"
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's ID, in [brackets] in list_folder and search_files"
    }
  },
  "required": [
    "file"
  ]
}