DigitalOcean setup guide

Overview

This guide explains how to prepare your DigitalOcean account so that emma can access your billing data, and what to provide during the connection setup.

emma requests your cost data from DigitalOcean directly, once a day — it never accesses your Droplets, volumes, or other resources. There is no billing export or storage to set up: you only need an API token with read access to billing.

Before you start

The token must come from the account that DigitalOcean bills:

• Your team belongs to an organization — an organization owner creates the token in the organization dashboard, on the API tab. One data source then covers all teams of the organization. A token created by a team inside an organization has no billing access, so such a team cannot be connected on its own.
• Your team is not in an organization — create the token on the team's API page. One data source covers that team. To import costs from another team, connect it as a separate data source.

Step 1 — Create an API token

1. Open Applications & API → Tokens in the DigitalOcean Control Panel (for an organization — the API tab of the organization dashboard) and click Generate New Token.

2. Enter a Token name (e.g. emma-billing).
3. Set Expiration to No expire. If the token expires, emma stops importing your costs until you reconnect the data source with a new token.
4. Under Scopes, select Custom Scopes. Select billing — it contains one scope, read. Leave all other scopes unselected.

5. Click Generate Token.
6. Copy the token. It starts with dop_v1_.

The token is shown only once. Copy it immediately.

Step 2 — Choose a backfill start date

Decide how far back emma should import historical costs on the first import. You enter this date in emma; nothing needs to be set up on the DigitalOcean side.

DigitalOcean provides daily cost data starting from 1 December 2025, so the date cannot be earlier. For an organization, each team's daily data starts on the later of 1 December 2025 and the date that team joined the organization — emma imports what is available from the date you enter.

What to enter in emma

What you should know

• Figures for recent days can change. DigitalOcean finalizes a month's invoice on the 1st of the following month. emma re-reads the current and the previous month on every daily import, so recent figures in your dashboards may change.
• Some costs drop to zero at the end of a month. DigitalOcean caps a Droplet's monthly charge at its monthly price, which a Droplet running since the 1st reaches after 28 days. On days 29–31 such Droplets show no cost; Droplets created later in the month, snapshots, and volumes are still charged. This is expected, not missing data.
• Where DigitalOcean costs appear. Expense Analysis, Budgets, Data Export, Cost Breakdown, and Resource Distribution.