> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maski.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# DigitalOcean

> Create a DigitalOcean Personal Access Token with custom domain scopes, so Maski can publish your custom-domain records.

DigitalOcean supports both ways of authorizing, but they are not equivalent, and on
this provider the token is the tighter one.

<Warning>
  DigitalOcean offers OAuth applications only account-wide **read** and **write**.
  Clicking **Connect with DigitalOcean** therefore grants Maski write access to your
  whole team account, not just DNS. A Personal Access Token can be narrowed to four
  `domain:` scopes. The granular scopes are a token-only feature at DigitalOcean.

  Connect is the faster path and Maski still uses the grant for one request and
  discards it. But if least privilege matters to you, paste a token.
</Warning>

<Info>
  Maski needs four scopes on **domain**: `read`, `create`, `update` and `delete`. The
  reads find your zone and let Maski skip records that are already correct. `delete`
  is needed only for one thing: replacing an existing mail host at your apex, which
  Maski never does without your explicit confirmation.
</Info>

## Create the token

<Steps>
  <Step title="Open Applications & API">
    In the DigitalOcean Control Panel choose **API** from the left sidebar to open
    **Applications & API**, then the **Tokens** tab. Under **Personal access
    tokens**, choose **Generate New Token**.
  </Step>

  <Step title="Name it and set an expiry">
    Give the token a name you will recognise later, for example `Maski DNS setup`,
    and choose when it expires. Maski uses it once, so the shortest option offered
    is enough.
  </Step>

  <Step title="Choose Custom Scopes">
    DigitalOcean offers **Full Access**, **Read Only**, and **Custom Scopes**.
    Choose **Custom Scopes**.

    Find **domain** in the scope list and tick all four:

    * `domain:read`
    * `domain:create`
    * `domain:update`
    * `domain:delete`

    Leave every other resource unticked. Read Only will not work, because Maski
    cannot publish anything with it. Full Access works but grants far more than is
    needed.
  </Step>

  <Step title="Copy the token">
    Choose **Generate Token**. The value starts with `dop_v1_` and is shown once.
    Copy it before you leave the page.
  </Step>

  <Step title="Paste it into Maski">
    Open your domain in the Maski dashboard. In **Set up automatically**, pick
    DigitalOcean, choose **Prefer to paste an API token instead?**, paste the token
    into **Personal Access Token**, and press **Review changes**.

    Maski reads your zone and shows you what it would change. Nothing is written
    until you press **Publish records**.
  </Step>
</Steps>

## Afterwards

Delete the token from the **Tokens** tab once your domain is set up. Maski does not
keep it and will not need it again.

## If it does not work

**"Your DNS provider rejected the request."** The token is missing one of the four
scopes, or it has expired. A Read Only token produces this too. Check the scope
list rather than regenerating blindly.

**Maski cannot find the zone.** The domain has to exist under **Networking**, then
**Domains**, in the same team the token belongs to, and DigitalOcean's nameservers
have to be the authoritative ones for it. Registering a domain elsewhere and
pointing it at DigitalOcean is fine, as long as the zone is present here.

**Connect sent you to the wrong team.** DigitalOcean asks for consent per team. If
you belong to more than one, make sure the team you approve is the one holding the
domain.

If none of that helps, add the records by hand from the checklist on the domain
page. A manually configured domain works exactly the same.