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

# Authentication

Use each credential only at its intended layer. Keep app and user credentials
in your backend. Give an agent runtime only its short-lived agent token.

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

## Credential layers

| Credential                  | Grants access to                                | Store it in          |
| --------------------------- | ----------------------------------------------- | -------------------- |
| App key and secret          | Identify your app and administer managed users. | Backend secret store |
| User access token           | File APIs, agents, and workspaces.              | Backend cache        |
| Agent runtime token         | File APIs within one workspace.                 | Worker or sandbox    |
| App access token            | Managed-user administration for your app.       | Backend cache        |
| Tenant tokens — Coming soon | Managed users in one tenant.                    | Backend secret store |

Managed-user routes accept HTTP Basic authentication with the app key and
secret, or an app access token in the `Authorization: Bearer` header. Create
your application through [Application Setup](/agentfs/docs/get-started/application-setup)
before using these routes. Tenant credentials are **Coming soon**.

Agent tokens expire after four hours by default and cannot be refreshed. Use
the returned `expires_in` value, in seconds, to schedule replacement. Your backend mints
a new token with the user's credential before the old one expires.

## Existing user flow

Connect an existing Dropbox user through your app's
[OAuth flow](/dropbox-api/docs/oauth). Request the file scopes needed by
the agent, along with the Agent Filesystem scopes provided during onboarding.
Keep the resulting user credential in your backend.

### 1. Create an agent

The authenticated user owns the new agent.

```bash
curl https://api.dropboxapi.com/2/agent_filesystem/agents/create \
  --header "Authorization: Bearer $USER_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "entries": [{
      "workspace": [{
        "path": "id:existing-folder-id",
        "role": {".tag": "read_write"}
      }]
    }]
  }'
```

Store the returned `agent_id`.

### 2. Mint an agent runtime token

```bash
curl https://api.dropboxapi.com/2/agent_filesystem/agents/access_token/mint \
  --header "Authorization: Bearer $USER_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "agent": {
      ".tag": "agent_id",
      "agent_id": "dbaid:agent"
    },
    "scope": "files.metadata.read files.content.write"
  }'
```

`scope` is a space-separated list. Supported scopes are `files.metadata.read`,
`files.metadata.write`, `files.content.read`, `files.content.write`, and
`account_info.read`. Include `account_info.read` for clients that must discover the
account's root namespace. Specify a subset for narrower access, such as
`"files.metadata.read files.content.read"` for a read-only token. Omit `scope`
to request all four file scopes. Each requested scope must also be granted to
the app and the user token; if either lacks a scope, the request fails.

Give the returned token to the agent runtime. It cannot change its workspace
or mint another token.

Writes through agent tokens are attributed to the agent's durable identity.
You can supply `session_external_id` when minting a token to associate it with
a run or job in your system. Recovery selects the agent's writes by timestamp
across all of its runtime tokens.

## Managed user flow

An app enabled for managed users can create API-only users and mint
short-lived user tokens for them. Follow the managed-user setup instructions
in [Application Setup](/agentfs/docs/get-started/application-setup). Keep the
app key and secret in your trusted backend.

### 1. Sign in as your app

Use the CLI from a trusted environment:

```bash
dbx login --app --app-key 'your-app-key' --profile provider
```

The CLI reads the app secret from `DBX_APP_SECRET` or a terminal prompt. It
saves the app key in the profile, but does not save the secret. Each command
that authenticates as the app reads the secret again.

If your backend already has an app access token for managed-user administration,
import it instead:

```bash
dbx login --app --token --profile provider
```

Supply the token through the hidden prompt or standard input. This saves the
app token in the profile, so app commands use it without asking for a secret.

### 2. Create a managed user

```bash
dbx user create app-user --name 'Example user' --profile provider
```

The CLI saves the user alias in the app profile. The optional `--email` is
contact metadata, not a sign-in or recovery address. Creation is not
idempotent: retrying a request that completed without returning a response
can create another user.

### 3. Sign in as the managed user

Mint a user token and save it in a separate profile:

```bash
dbx login --user app-user \
  --app-profile provider \
  --profile managed-user
```

Use `--profile managed-user` with agent and workspace commands. To mint a
token for backend API calls without saving it as a profile, run:

```bash
dbx user token app-user --profile provider
```

This prints only the token. Both commands request all supported managed-user
scopes by default. Use comma-separated or repeated `--scope` flags to request
a subset. Every requested scope must be enabled for the app;
`dbx login --user` also requires `account_info.read` to identify the user.

Managed-user tokens cannot be refreshed. Run `dbx login --user` again before
the token expires to replace it while preserving the profile's agent aliases.
For tokens minted with `dbx user token`, use `--output=json` to read
`result.expires_in`, `result.expires_at`, and `result.scopes`.

#### Sign in with a token issued elsewhere

The environment signing in as the managed user does not need app credentials.
On your trusted backend, mint the token with its expiry and scopes:

```bash
dbx user token app-user --profile provider --output=json > user-token.json
```

Deliver that file privately to the environment that will use the user account,
then sign in there:

```bash
dbx login --token --profile managed-user < user-token.json
```

This CLI flow is useful for development and testing. Managed-user tokens are
currently short-lived and do not renew automatically. To continue after expiry,
have your app issue a new token and sign in again with `dbx login --token`.

Continue with the [Mount guide](/agentfs/docs/concepts/mount#managed-user) to
create an agent and mount its workspace. Give only the agent token to the
runtime.

### Direct API alternative

For backend integrations that call the API directly, create a user and mint
its token with the app key and secret. These examples use `curl --user` with
the app key; curl prompts for the secret.

#### Create a managed user

Send exactly one entry and omit `tenant`. The optional name and email are
profile metadata. The email does not become a sign-in or recovery address.

```bash
curl https://api.dropboxapi.com/2/agent_filesystem/users/create \
  --user "$DROPBOX_APP_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"entries": [{"name": "Example user"}]}'
```

Save the returned `user_public_id`. Creation is not idempotent, so retrying a
request that completed without returning a response can create another user.
Use `users/get` or `users/list` to inspect your app's active managed users.
For listing, omit `tenant` and continue while `next_cursor` is present, even
if a page is empty.

#### Mint a managed-user token

```bash
curl https://api.dropboxapi.com/2/agent_filesystem/users/access_token/mint \
  --user "$DROPBOX_APP_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      ".tag": "user_public_id",
      "user_public_id": "opaque-app-bound-user-id"
    },
    "scopes": [
      "account_info.read",
      "private:agent_filesystem.agents.manage",
      "private:agent_filesystem.agents.restore",
      "files.metadata.read",
      "files.metadata.write",
      "files.content.read",
      "files.content.write"
    ]
  }'
```

Replace the example ID with the saved `user_public_id`. `scopes` is a required
array with at least one scope and no duplicates. The example lists every
supported managed-user scope; request only those you need. Applications created
through [Application Setup](/agentfs/docs/get-started/application-setup) are
configured for this flow.

The token cannot be refreshed. Use `expires_in` to schedule minting a new user
token with the app credentials. Use the user token to create files and agents,
edit workspaces, and mint agent tokens. Give only the agent token to the
runtime.

## Tenant flow — Coming soon

Add a tenant when a customer, business unit, or project needs a separate
administration credential:

1. Create a tenant with the app token.
2. Exchange its one-time authorization code for tenant access and refresh
   tokens.
3. Use the tenant access token to create users in that tenant.
4. Use the tenant token and a user's `user_public_id` to mint user access
   tokens.

A tenant token cannot manage users outside its tenant. After you mint a user
token, use the same file and agent APIs as the existing user flow.

## Token storage

Your backend should:

1. Store each connected user's Dropbox account ID for your OAuth records.
   Store the app-bound `user_public_id` returned for AgentFS users and agent
   owners, along with agent IDs.
2. Store user refresh tokens in your backend secret store and cache access
   tokens by expiry time.
3. Bind each user account ID to the authenticated customer session in your
   product.
4. Give each runtime only its own agent token and task input.

Do not accept a user identifier from an untrusted client without checking that
it belongs to the current customer and session.

## Stop access

* Revoke one runtime token with
  [auth/token/revoke](https://www.dropbox.com/developers/documentation/http/documentation#auth-token-revoke).

  To revoke one runtime token, send a POST request with no body:

  ```bash
  curl --request POST https://api.dropboxapi.com/2/auth/token/revoke \
    --header "Authorization: Bearer $AGENT_ACCESS_TOKEN"
  ```

  Other independently minted agent tokens remain active. To resume work, mint
  a new token with the user token.

* Delete an agent to revoke its runtime tokens and prevent new ones.

* Delete a managed user with `dbx user delete app-user --profile provider` or
  [`users/delete`](/agentfs/api-reference/agent-filesystem/users-delete), using
  the owning app's credentials, to disable the account and schedule its data
  for deletion. See [Delete managed users](/agentfs/docs/concepts/identity#delete-managed-users)
  for batch deletion and CLI alias cleanup.

* Edit a workspace to change the files available to an agent.

* Disable the app to stop issuing new tokens for the integration.

Managed-user deletion is irreversible, and file purge is asynchronous. Tenant
administration is **Coming soon**.

Existing short-lived tokens expire automatically. Dropbox provides current
revocation timing during Private Preview onboarding.