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.

Credential layers

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

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

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. Keep the app key and secret in your trusted backend.

1. Sign in as your app

Use the CLI from a trusted environment:

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:

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

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:

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:

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:

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:

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

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

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

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

  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, using the owning app’s credentials, to disable the account and schedule its data for deletion. See 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.