Dropbox User Management API Guide

Auth method: OAuth 2.0

Setup steps

1. Register an app at https://www.dropbox.com/developers/apps and select 'Dropbox Business API' app type.
2. Choose required permission scopes (e.g., members.read, members.write) during app creation.
3. Implement OAuth 2.0 authorization code flow: redirect admin to https://www.dropbox.com/oauth2/authorize with client_id, response_type=code, and token_access_type=offline.
4. Exchange the returned authorization code for an access token and refresh token via POST https://api.dropbox.com/oauth2/token.
5. Use the access token in the Authorization header as 'Bearer ' for all API requests.
6. For team-level operations, the authorizing user must be a Dropbox Business team admin.

Required scopes

List team members

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/list/v2
• Watch out for: Use /team/members/list/continue/v2 with the returned cursor to paginate. The v2 endpoint is preferred over the deprecated v1.

Request example

POST /2/team/members/list/v2
Authorization: Bearer <team_token>
Content-Type: application/json

{"limit": 100}

Response example

{
  "members": [{"profile": {"team_member_id": "dbmid:abc", "email": "user@example.com", "status": {".tag": "active"}}}],
  "cursor": "ZtkX9...",
  "has_more": true
}

Get member info

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/get_info/v2
• Watch out for: Accepts lookup by email, team_member_id, or external_id. Returns a tagged union; check the .tag field for 'member_info' vs 'id_not_found'.

Request example

POST /2/team/members/get_info/v2
Authorization: Bearer <team_token>
Content-Type: application/json

{"members": [{"email": "user@example.com", ".tag": "email"}]}

Response example

[
  {".tag": "member_info", "profile": {"team_member_id": "dbmid:abc", "email": "user@example.com", "given_name": "Jane", "surname": "Doe", "status": {".tag": "active"}}}
]

Add team member(s)

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/add/v2
• Watch out for: Supports batch add of up to 20 members per call. Response is async if the team is large; poll /team/members/add/job_status/check/v2 when response tag is 'async_job_id'.

Request example

POST /2/team/members/add/v2
Authorization: Bearer <team_token>
Content-Type: application/json

{"new_members": [{"member_email": "newuser@example.com", "send_welcome_email": false, "role": {".tag": "member_only"}}]}

Response example

{
  "complete": [
    {".tag": "success", "profile": {"team_member_id": "dbmid:xyz", "email": "newuser@example.com", "status": {".tag": "invited"}}}
  ]
}

Update member profile

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/set_profile/v2
• Watch out for: Cannot change email via this endpoint. Email changes must be initiated by the member or via admin console.

Request example

POST /2/team/members/set_profile/v2
Authorization: Bearer <team_token>
Content-Type: application/json

{"user": {"team_member_id": "dbmid:abc", ".tag": "team_member_id"}, "new_given_name": "Jane", "new_external_id": "EMP-001"}

Response example

{
  "profile": {"team_member_id": "dbmid:abc", "email": "user@example.com", "given_name": "Jane", "external_id": "EMP-001"}
}

Suspend member

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/suspend
• Watch out for: Setting wipe_data=true immediately deletes the member's Dropbox data from their devices. This is irreversible for local device data.

Request example

POST /2/team/members/suspend
Authorization: Bearer <team_token>
Content-Type: application/json

{"user": {"team_member_id": "dbmid:abc", ".tag": "team_member_id"}, "wipe_data": false}

Response example

{}

Unsuspend member

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/unsuspend
• Watch out for: Member must be in 'suspended' status; calling on an active member returns an error.

Request example

POST /2/team/members/unsuspend
Authorization: Bearer <team_token>
Content-Type: application/json

{"user": {"team_member_id": "dbmid:abc", ".tag": "team_member_id"}}

Response example

{}

Remove member

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/remove
• Watch out for: Remove is async; poll /team/members/remove/job_status/check with the returned async_job_id. If transfer_dest_id is omitted, files remain in a deactivated account accessible only to admins.

Request example

POST /2/team/members/remove
Authorization: Bearer <team_token>
Content-Type: application/json

{"user": {"team_member_id": "dbmid:abc", ".tag": "team_member_id"}, "wipe_data": false, "transfer_dest_id": {"team_member_id": "dbmid:mgr", ".tag": "team_member_id"}}

Response example

{".tag": "async_job_id", "async_job_id": "34g93opqe..."}

Set admin permissions

• Method: POST
• URL: https://api.dropboxapi.com/2/team/members/set_admin_permissions/v2
• Watch out for: Only a team_admin token can elevate another member to team_admin role. user_management_admin tokens cannot grant team_admin.

Request example

POST /2/team/members/set_admin_permissions/v2
Authorization: Bearer <team_token>
Content-Type: application/json

{"user": {"team_member_id": "dbmid:abc", ".tag": "team_member_id"}, "new_role": {".tag": "user_management_admin"}}

Response example

{
  "team_member_id": "dbmid:abc",
  "role": {".tag": "user_management_admin"}
}

• Rate limits: Dropbox enforces per-route rate limits. Most Business API endpoints allow up to 1,000 requests per minute per team token. Exceeding limits returns HTTP 429. Dropbox recommends exponential backoff.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 responses include a Retry-After header indicating seconds to wait. Dropbox does not publish exact per-route limits publicly; limits may vary by endpoint. Batch endpoints (e.g., members/add/v2) are preferred to reduce request volume.
• Pagination method: cursor
• Default page size: 1000
• Max page size: 1000
• Pagination pointer: cursor

• Webhooks available: Yes
• Webhook notes: Dropbox supports webhooks for file/folder change notifications via the Dropbox API. For team-level user management events (member added, removed, suspended), Dropbox does not provide native push webhooks; instead, team activity is available via the Team Log API.
• Alternative event strategy: Poll /team/log/get_events for user management audit events (member_add, member_remove, member_suspend, member_change_admin_role, etc.). Supports filtering by event category and cursor-based pagination.
• Webhook events: file/folder change notifications (via webhook endpoint registered in app console)

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Standard (formerly Business), Advanced, or Enterprise

• Endpoint: https://api.dropbox.com/2/team/scim/v2

• Supported operations: GET /Users – list users, GET /Users/{id} – get user by SCIM ID, POST /Users – provision new user, PUT /Users/{id} – replace user attributes, PATCH /Users/{id} – update user attributes (activate/deactivate), DELETE /Users/{id} – deprovision user, GET /Groups – list groups, POST /Groups – create group, PATCH /Groups/{id} – update group membership, DELETE /Groups/{id} – delete group

Limitations:

• SSO must be enabled on the Dropbox team before SCIM provisioning can be activated.
• SCIM is supported via Azure AD (Entra ID), Google Cloud Identity, Okta, and OneLogin; direct SCIM token issuance is available for other IdPs.
• Dropbox Sign (formerly HelloSign) does NOT support SCIM provisioning.
• SCIM provisioning requires Standard plan or above; Essentials/Professional plans do not include SCIM.
• Group provisioning via SCIM is supported but group-based folder permissions must still be configured in Dropbox admin console.
• SCIM token is generated in the Dropbox Admin Console under Authentication > SCIM; it does not use OAuth 2.0.

Three scenarios cover the majority of lifecycle automation needs. For provisioning, POST /team/members/add/v2 supports batch adds of up to 20 members per call; poll /team/members/add/job_status/check/v2 when the response tag is async_job_id, then extract team_member_id for downstream correlation.

Set external_id via /team/members/set_profile/v2 to anchor the Dropbox identity to your HR system record in the identity graph.

For offboarding, suspend first with wipe_data=false to preserve data, then POST /team/members/remove with transfer_dest_id pointing to the departing member's manager; removal is also async - poll /team/members/remove/job_status/check until complete.

For auditing, POST /team/members/list/v2 with limit=1000 and paginate via /team/members/list/continue/v2 using the returned cursor; filter client-side on status. tag == 'active'.

Do not cache cursors across sessions - they expire on inactivity.

Provision a new employee

1. POST /team/members/add/v2 with member_email, given_name, surname, send_welcome_email=false, and role=member_only.
2. Check response: if .tag is 'async_job_id', poll POST /team/members/add/job_status/check/v2 until .tag is 'complete'.
3. Extract team_member_id from the completed response for future operations.
4. Optionally POST /team/members/set_profile/v2 to set external_id for HR system correlation.

Watch out for: Member status will be 'invited' until the user accepts the invitation. Some profile fields (e.g., display_name) are not settable until the account is active.

Offboard a departing employee

1. POST /team/members/suspend with wipe_data=false to immediately revoke access while preserving data.
2. POST /team/members/remove with transfer_dest_id set to the departing member's manager team_member_id and wipe_data=false.
3. Poll POST /team/members/remove/job_status/check with the returned async_job_id until status is 'complete'.
4. Verify file transfer completion in the Dropbox Admin Console or via /team/log/get_events filtered to member_transfer_account_contents.

Watch out for: Suspension and removal are separate steps; skipping suspension and going directly to removal still revokes access immediately, but suspension allows a grace period for data review before permanent removal.

Audit all active team members

1. POST /team/members/list/v2 with limit=1000 to retrieve the first page of members.
2. While has_more is true, POST /team/members/list/continue/v2 with the returned cursor.
3. Filter results client-side for members where status.tag == 'active'.
4. For each active member, extract team_member_id, email, role, joined_on, and external_id for the audit report.

Watch out for: The cursor expires after a period of inactivity; complete the full pagination in a single session. Do not cache cursors across days for incremental sync without verifying cursor validity.

Three API behaviors are the most common sources of integration bugs. First, the async job pattern: callers who treat add and remove as synchronous will miss failures silently - always implement the poll loop.

Second, email is not updatable via /team/members/set_profile/v2; email changes must go through the admin console or be member-initiated, which breaks any automated identity reconciliation flow that assumes email is a mutable field.

Third, Dropbox Sign does not expose a SCIM or API provisioning surface, so any identity graph that includes Dropbox Sign users requires a separate, manual management path - there is no API workaround available at this time.

Rate limits return HTTP 429 with a Retry-After header; Dropbox does not publish exact per-route numeric limits, so implement exponential backoff unconditionally rather than tuning to a specific threshold.