Locking Down Collaborative Files

Many collaborative projects — a podcast with international guests, a skyscraper blueprint, a feature film — converge on a single source file that multiple people need to update. Dropbox file locking, available to Dropbox Business users, addresses the coordination problem this creates: preventing unwanted edits, moves, or deletions while a collaborator is actively working on a file.

A locked file can still be viewed and downloaded, and other users can see who holds the lock. Only the lock holder can edit or unlock the file; team admins can override locks. Locking applies only to files in shared folders. The key API behaviors are implemented through two new endpoints: /files/lock_file_batch and /files/unlock_file_batch. To follow the examples yourself, create a shared folder named file-lock-article with two text files: test-doc.txt and another-doc.txt.

Basic User Workflow

Start with a Dropbox app that has Full Dropbox access and a generated user access token. With the /files/lock_file_batch endpoint, you submit a list of entries, each specifying a file by path (either a file path or file id):

curl -X POST \
  https://api.dropboxapi.com/2/files/lock_file_batch \
  -H 'Authorization: Bearer <user_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "entries": [
                {
                        "path": "/file-lock-article/test-doc.txt"
                },
                {
                        "path": "id:7AObMBEU53AAAAAAAAAASw"
                },
                {
                        "path": "/throw-an-error"
                }
        ]
}'

The response reports the result per entry:

{
    "entries": [
        {
            ".tag": "success",
            "metadata": // file metadata,
            "lock": // file lock info
        },
        {
            ".tag": "success",
            "metadata": // file metadata,
            "lock": // file lock info
        },
        {
            ".tag": "failure",
            "failure": // error message
        }
    ]
}

Locked files reveal lock information in their metadata. Calls like /files/get_metadata or /files/list_folder will return a file_lock_info property for any locked file. Checking the locked files in the folder:

curl -X POST \
  https://api.dropboxapi.com/2/files/list_folder \
  -H 'Authorization: Bearer <user_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "path": "/file-lock-article"
}'

Produces metadata with file lock details:

"file_lock_info": {
    "is_lockholder": false,
    "lockholder_name": "Taylor K",
    "lockholder_account_id": "dbid:AAB9bIvxKmEflS5houxLa198BIEaS_iYZI",
    "created": "2019-12-19T18:03:37Z",
    "is_locked": true
}

To release a lock, call /files/unlock_file_batch. Only the original lock holder (or a team admin) can perform the unlock:

curl -X POST \
  https://api.dropboxapi.com/2/files/unlock_file_batch \
  -H 'Authorization: Bearer <user_access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "entries": [
                {
                        "path": "/file-lock-article/test-doc.txt"
                },
                {
                        "path": "id:7AObMBUU53AAAAAAAAAARA"
                }
        ]
}'

An unlock confirmation returns success.

Admin Overrides in Team Apps

Business API integrations are more interesting. Consider a compliance scanner that walks a team's folder hierarchy, downloads files for inspection, and quarantines policy violations. Locked files don't impede scanning, but they must be unlocked before they can be moved.

When using a team member file access token, you target requests at a specific user with the Dropbox-API-Select-Admin header. Parsing metadata from a /files/list_folder or /files/get_metadata response shows the lock state; locked files are distinguishable from unlocked ones solely by presence of the file_lock_info property. For a locked file such as test-doc.txt:

curl -X POST \
  https://api.dropboxapi.com/2/files/get_metadata \
  -H 'Authorization: Bearer <team_file_access_token>' \
  -H 'Content-Type: application/json' \
  -H 'Dropbox-API-Select-Admin: dbmid:AAAIrHhxSNGhQ0QD4hZ85lYRDSEhQdovJTg' \
  -d '{
        "path": "/file-lock-article/test-doc.txt"
}'

To unlock a file as an admin, issue the /files/unlock_file_batch request with the Dropbox-API-Select-Admin header set to the team member id:

curl -X POST \
  https://api.dropboxapi.com/2/files/unlock_file_batch \
  -H 'Authorization: Bearer <team_file_access_token>' \
  -H 'Content-Type: application/json' \
  -H 'Dropbox-API-Select-Admin: dbid:AADuXdtqA88UpveXxu7rcTSo64ADcrWnBMk' \
  -d '{
        "entries": [
                {
                        "path": "/file-lock-article/test-doc.txt"
                }
        ]
}'

The file is now unlocked and ready to move to quarantine, just as the Admin Console would permit.

Integration Notes

  • Team-linked apps must use a team file access token plus either the Dropbox-API-Select-User or Dropbox-API-Select-Admin header.
  • The robust way to test a lock is the presence of file_lock_info in metadata rather than assuming lock state.
  • Both file paths and file ids are valid inputs to the file locking endpoints.

File locking expands the range of workflows you can support in your app — collaborative check-in/check-out being the obvious use case — but it also requires additional logic in existing applications that parse or manage files autonomously. The API behavior mirrors what a user sees in the Dropbox UI, and testing with the desktop client while building against the user or team endpoints is helpful for verifying behavior.