# Dropbox OAuth

Connect Dropbox to read and write files from your workflows.

JsWorkflows provides a platform-managed Dropbox OAuth app. You do not need to create a Dropbox app or provide credentials.

## Available scopes

| Resource | Operation | Scope |
| --- | --- | --- |
| Files | Read & write files | `files.content.read`, `files.content.write` |

## Connecting

1. Go to **OAuth Connections → Add Connection → Dropbox**.
2. Select the resources and operations your workflow needs.
3. Sign in with your Dropbox account and grant the requested permissions.
4. Give the connection a handle (e.g., `my-dropbox`).

Use lowercase letters, numbers, and hyphens only for the handle.

Access tokens are refreshed automatically when they expire.

## Example: upload a file

```js
export class Workflow {
  async start(data, _headers, api) {
    await api.scheduleNextStep({
      delay: 10,
      action: 'uploadReport',
      payload: { orderId: data.id, total: data.total_price },
    });
  }

  async uploadReport({ orderId, total }, _headers, api) {
    const { token, error } = await api.getOAuthToken('my-dropbox');
    if (error || !token) throw new Error(error || 'Missing Dropbox token');

    const content = `Order ID,Total\n${orderId},${total}`;
    const bytes = new TextEncoder().encode(content);

    const response = await fetch('https://content.dropboxapi.com/2/files/upload', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/octet-stream',
        'Dropbox-API-Arg': JSON.stringify({
          path: `/reports/order-${orderId}.csv`,
          mode: 'overwrite',
        }),
      },
      body: bytes,
    });

    if (!response.ok) {
      throw new Error(`Dropbox API ${response.status}: ${await response.text()}`);
    }

    const file = await response.json();
    console.log(`Uploaded ${file.path_display || file.name}`);
  }
}
```

`/2/files/upload` expects the file content in the request body and the file arguments in the `Dropbox-API-Arg` header.

## Example: download a file

```js
const { token, error } = await api.getOAuthToken('my-dropbox');
if (error || !token) throw new Error(error || 'Missing Dropbox token');

const resp = await fetch('https://content.dropboxapi.com/2/files/download', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Dropbox-API-Arg': JSON.stringify({ path: '/reports/config.json' }),
  },
});

if (!resp.ok) {
  throw new Error(`Dropbox API ${resp.status}: ${await resp.text()}`);
}

const text = await resp.text();
```

`/2/files/download` returns file bytes in the response body. Dropbox file metadata is returned in the `Dropbox-API-Result` response header.