URL: /api/api-keys-and-scopes

---
title: API keys and scopes
description: Mint keys, choose scopes, rotate, and revoke.
---

API keys are durable bearer tokens prefixed `dg_live_` (production) or `dg_test_` (sandbox).

## Mint a key

<Steps>
  <Step title="Open the dashboard">
    Go to [API keys](https://app.domaingenius.com.au/dashboard/api-keys).
  </Step>
  <Step title="Pick scopes">
    Select the scopes the key needs. Less is more — see the matrix below.
  </Step>
  <Step title="Copy the key">
    The full key is shown once. Store it in a secrets manager. We only keep the prefix and a hash.
  </Step>
</Steps>

You can also mint keys via the API itself — see [`POST /api/v1/me/api-keys`](/api/api-keys#create-api-key).

## Scope matrix

| Scope | What a key with this scope can do |
| --- | --- |
| `availability:read` | Check whether domains are registered |
| `domains:read` | List org domains, read settings, status, health |
| `domains:write` | Update auto-renew, redirects, privacy, sale status; renew; transfer |
| `dns:read` | List DNS records and active presets |
| `dns:write` | Create, update, delete DNS records; apply or remove presets |
| `contacts:read` | Read org contacts and per-domain contact assignments |
| `contacts:write` | Create, update, delete contacts; assign or unassign roles |
| `orgs:read` | Read org members and audit logs |
| `orgs:write` | Add or remove members; update org settings |
| `billing:read` | Read balance, transactions, invoices |
| `billing:write` | Top up balance, configure auto-top-up |

A request that needs a scope your key lacks gets HTTP 403 with `{ "detail": "Missing scope: dns:write" }`.

## Rotation

There is no expiry on a key. Rotate by minting a new key, deploying it, then deleting the old one in the dashboard. Deleted keys stop working immediately — there is no grace period.

## Test mode

`dg_test_` keys hit the same API but never call the registrar. Domain operations return synthetic confirmations. Use them in CI.

## Revocation triggers

A key is killed automatically if:

- The owning user is disabled.
- The key's last-used IP enters our abuse list.
- A duplicate key value appears in a public commit (we scan GitHub).

You'll get an email and the key flips to `revoked` in the dashboard.