Dropbox

Let hires find and read files in Dropbox, and upload, share or delete only as you allow.

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

With Dropbox, a hire can:

find files by name (and by content, on Dropbox plans that search inside files),
list what's in a folder,
read a file as text: Word, Excel, PowerPoint and OpenDocument files, which Roster turns into text itself, and text files (txt, md, csv, json…). Of a large text file it reads the start. Other files (PDFs, images) show their name, size and date only, never their content. Dropbox Paper docs aren't read yet.

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 your team or for anyone, optionally ending after a number of days (on plans that allow it). This always asks a person first.
delete a file. This always asks a person first. Dropbox keeps deleted files for a while, so they can be restored.

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

1. Make a Dropbox app

Open dropbox.com/developers/apps and click Create app: Scoped access, then Full Dropbox (or App folder to keep Roster to one folder of its own).
Permissions: tick files.metadata.read and files.content.read. To allow changes, also files.content.write and sharing.write. Click Submit.
Settings → OAuth 2 → Redirect URIs: add the address Roster shows on the connection. It ends in /api/integrations/dropbox/oauth/callback.
Copy the App key and App secret.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for Dropbox and choose it.
Paste the App key and App secret.
What hires may do: Find and read files, or also upload, share and delete. Changing this later means connecting again.
Click Connect with Dropbox and sign in with the account hires should use.

3. Give hires access

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

Folders: paths like /Clients. Upper and lower case don't matter, as in Dropbox. Files in subfolders count. Leave it empty for everything the account can see.

When it asks first

What the hire does	Asks a person
Makes a shared link	always
Deletes a file	always
Uploads a file with a taken name	only when it asks to replace the old file

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

If something goes wrong

"Isn't connected yet": click Connect with Dropbox on the connection.
Uploads or links fail with a permissions error: the app is missing files.content.write or sharing.write. Tick them, then connect again.
A link for your team comes back for anyone: on personal accounts Dropbox only makes public links.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Dropbox and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

OAuth 2.0

The App key and App secret of the app you made for Roster at dropbox.com/developers/apps.

For: What hires may do: Find and read files.

Requested scopes:

files.metadata.read
files.content.read

OAuth 2.0

The App key and App secret of the app you made for Roster at dropbox.com/developers/apps.

For: What hires may do: Also upload, share (asks first) and delete (asks first).

Requested scopes:

files.metadata.read
files.content.read
files.content.write
sharing.write

Connection fields

Dropbox connection fields
Field	What to provide
OAuth app client ID `clientId` Optional	The App key and App secret of the app you made for Roster at dropbox.com/developers/apps.
OAuth app client secret `clientSecret` Optional · sealed secret	Use the value for your account or connection.
What hires may do `access` Optional	Read only asks Dropbox for less, and hires get no tool that changes anything. Changing this may mean signing in again. Choices: Find and read files (read); Also upload, share (asks first) and delete (asks first) (write). Starts with: `read`.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Dropbox per-hire limits
Field	What to provide
Folders `folders` Optional	Folders the hire may use, as paths like /Clients. Files in their subfolders count. Leave empty for everything the connection can see.

Actions

6 actions: 3 only read and 3 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

6 of 6 actions. Open an action for its arguments and full input schema.

search_filesRead only

Find files in Dropbox by words in their name or content, optionally inside one folder.

Approval: Uses your workspace and hire approval settings.

Arguments for search_files
Argument	Type	Details
`text`Required	string	words to look for
`folder`Optional	string	a folder's path, like /Clients
`limit`Optional	integer	See input schema below.Default: `20`

Full input schema (JSON)

{
  "$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 path, like /Clients"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "text"
  ]
}

list_folderRead only

What's directly inside a Dropbox folder: files and subfolders, newest first where Dropbox sorts.

Approval: Uses your workspace and hire approval settings.

Arguments for list_folder
Argument	Type	Details
`folder`Optional	string	a folder (path); leave out for the top
`limit`Optional	integer	See input schema below.Default: `50`

Full input schema (JSON)

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

read_fileRead only

Read a Dropbox file as text: text files (the start of large ones), Word, Excel, PowerPoint and OpenDocument files. Other files (PDFs, images) show their details only.

Approval: Uses your workspace and hire approval settings.

Arguments for read_file
Argument	Type	Details
`file`Required	string	the file's path, like /Clients/notes.md (from list_folder or search_files)

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's path, like /Clients/notes.md (from list_folder or search_files)"
    }
  },
  "required": [
    "file"
  ]
}

upload_fileRead and write

Save text as a file in a Dropbox folder (a note, a CSV, a Markdown report). It never overwrites: if the name is taken it says so, and replace: true replaces the file after a person approves.

Approval: when it would replace a file that's already there.

Available with: What hires may do: Also upload, share (asks first) and delete (asks first).

Arguments for upload_file
Argument	Type	Details
`folder`Required	string	a folder's path, like /Clients
`name`Required	string	the file's name with its extension, like summary.md or rates.csv
`text`Required	string	the file's whole content, as text
`replace`Optional	boolean	replace a file of the same name (asks a person first)Default: `false`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "folder": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "a folder's path, like /Clients"
    },
    "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"
  ]
}

share_linkRead and write

Make a link to a Dropbox file for people in the organisation, or anyone who has it. It waits for a person's approval: Roster asks in the thread and makes the link, once, when they approve.

Approval: Always asks for approval.

Available with: What hires may do: Also upload, share (asks first) and delete (asks first).

Arguments for share_link
Argument	Type	Details
`file`Required	string	the file's path, like /Clients/notes.md (from list_folder or search_files)
`audience`Optional	"organization" \| "anyone"	anyone with the link, or only people signed in to the organisationDefault: `"organization"`
`expires_in_days`Optional	integer	when the link stops working, if the service supports it

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's path, like /Clients/notes.md (from list_folder or 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"
  ]
}

delete_fileRead and write

Delete a Dropbox file (Dropbox keeps it for a while so it can be restored). It waits for a person's approval: Roster asks in the thread and deletes it, once, when they approve. Folders aren't deleted here.

Approval: Always asks for approval.

Available with: What hires may do: Also upload, share (asks first) and delete (asks first).

Arguments for delete_file
Argument	Type	Details
`file`Required	string	the file's path, like /Clients/notes.md (from list_folder or search_files)

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "the file's path, like /Clients/notes.md (from list_folder or search_files)"
    }
  },
  "required": [
    "file"
  ]
}

Watches and incoming events

No built-in watch is declared. Give a hire a scheduled responsibility if it should check this service regularly.
No incoming webhook handler is declared for this integration.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Make a Dropbox appCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

When it asks firstCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

OAuth 2.0

OAuth 2.0

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Make a Dropbox app

2. Connect it in Roster

3. Give hires access

When it asks first

If something goes wrong