> This page is for Agent Filesystem.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dropboxapi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server.

# 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.

> **Warning**
>
> Agent Filesystem is in Private Preview and is subject to change. Contact
> your Dropbox representative to request access.

## Identity hierarchy

```mermaid
flowchart TD
    App["App"] --> UserA["User"]
    App --> UserB["User"]
    UserA --> AgentA["Agent"]
    UserA --> AgentB["Agent"]
    AgentA --> WorkspaceA["Workspace rules"]
    AgentB --> WorkspaceB["Workspace rules"]
```

| Concept              | Use it for                                                                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| App                  | Connect your product to Agent Filesystem. Keep credentials in your backend.                                                                             |
| User                 | Connect an existing Dropbox user or create an API-only managed user.                                                                                    |
| Agent                | Give an automated actor a durable identity. Each agent belongs to one user.                                                                             |
| Workspace            | Set which of the user-accessible files and folders the agent may read or write. A workspace is a set of access rules, not a separate content container. |
| Managed user         | Store content for a person or service in your product without a Dropbox sign-in flow.                                                                   |
| Tenant — Coming soon | Add a separate administration and credential boundary.                                                                                                  |

## 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`:

```bash
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`](/agentfs/api-reference/agent-filesystem/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:

```bash
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`](/agentfs/api-reference/agent-filesystem/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](/agentfs/docs/concepts/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](/agentfs/docs/concepts/authentication) for the token
flow or [Workspaces](/agentfs/docs/concepts/workspaces) for access rules.