Identity

Agent Filesystem separates the user who owns access from the agent that does the work. This gives each automated actor its own identity and access limits.

Identity hierarchy

Users

Connect an existing Dropbox user through your app’s OAuth flow. Store the user’s Dropbox account ID with the matching record in your system. When you create an agent, its response includes owner_user_public_id, an opaque user ID bound to your app. Managed-user routes also use app-bound public IDs in their user selectors.

Apps enabled for managed users can create API-only users and mint their user tokens. Save the returned user_public_id in your system. Each create request accepts exactly one user without a tenant. An optional email is contact metadata; it is not the user’s sign-in or recovery address.

Use users/get and users/list to retrieve active managed users created by your app. Creating a user is not idempotent: retrying a request that completed without returning a response can create another user.

Update a managed user

Use dbx user update with the owning app’s profile to replace a user’s display name and contact email. The user argument can be an alias saved in that profile or a user_public_id:

dbx user update app-user \
  --name 'Updated example user' \
  --email 'producer@example.com' \
  --profile provider

Include every value you want to keep. Omitting --name clears the name; omitting --email clears the contact email. With neither flag, both fields are cleared. The sign-in and recovery address stays the same.

For direct API integrations, use users/update with app authentication. It has the same replacement behavior: omitted fields are cleared.

Delete managed users

Use dbx user delete with the owning app’s profile to disable managed users and schedule their account data for deletion:

dbx user delete app-user --profile provider

The command accepts up to 100 user aliases or public IDs. Deletion is irreversible, and file purge is asynchronous. If a request fails, some users may already be deleted; retry the same command to finish deletion.

After a successful API response, the CLI removes matching user aliases from the selected app profile. It keeps aliases when the request fails so you can retry with the same names.

For direct API integrations, use users/delete with app authentication. Direct API deletion leaves local CLI aliases in place; dbx user delete also handles their cleanup.

Agents and runtimes

An agent is a durable identity owned by a user. Store its returned agent ID. Use that ID to update its workspace and mint short-lived runtime tokens.

Writes through an agent token are attributed to the same agent across token replacements. Recovery uses that identity to inspect the agent’s changes and undo its writes after a chosen timestamp.

An agent runtime is the sandbox, VM, container, or process that runs the agent code. Give the runtime only its short-lived agent token. Do not give it app or user credentials.

Tenants — Coming soon

Tenants are planned as an optional feature. They will provide a separate credential for creating managed users and minting their tokens. A tenant credential will manage only users in that tenant.

Users will not need a tenant. Tenant membership will not change user file permissions or agent workspace rules.

Next, see Authentication for the token flow or Workspaces for access rules.