Authentication

Overview

DNScale uses API keys for authentication. Each API key is scoped to a customer account and carries specific permissions that control what operations it can perform.

For human login architecture and identity-provider concepts, see What Is SSO?. SSO governs browser-based user authentication; API keys still need their own scope, storage, rotation, and revocation controls.

Creating API Keys

Via the Dashboard

1. Navigate to DNScale Dashboard → Settings → API Keys
2. Click Create API Key
3. Enter a name, select the required action scopes, and choose a zone/DNS-name boundary
4. Copy and securely store the key—it's only shown once

Via the API

Create a key for a specific user:

curl -X POST https://api.dnscale.eu/v1/users/{user_id}/apikeys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME Automation",
    "scopes": "[\"zones:read\",\"records:read\",\"records:write\"]",
    "zone_scopes": [{
      "zone_id": "11111111-1111-4111-8111-111111111111",
      "record_access": "names",
      "record_names": ["_acme-challenge", "_acme-challenge.api"]
    }]
  }'

Response:

{
  "status": "success",
  "data": {
    "api_key": {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "ACME Automation",
      "key": "dnscale_xxxxxxxxxxxxxxxxxxxx",
      "scopes": "[\"zones:read\",\"records:read\",\"records:write\"]",
      "zone_ids": ["11111111-1111-4111-8111-111111111111"],
      "zone_scopes": [{
        "zone_id": "11111111-1111-4111-8111-111111111111",
        "record_access": "names",
        "record_names": ["_acme-challenge", "_acme-challenge.api"]
      }],
      "created_at": "2026-09-05T10:30:00Z"
    }
  }
}

Using API Keys

Include your API key in the Authorization header:

curl https://api.dnscale.eu/v1/zones \
  -H "Authorization: Bearer dnscale_live_xxxxxxxxxxxxxxxxxxxx"

Managing API Keys

List API Keys

curl https://api.dnscale.eu/v1/users/{user_id}/apikeys \
  -H "Authorization: Bearer YOUR_API_KEY"

Get API Key Details

curl https://api.dnscale.eu/v1/users/{user_id}/apikeys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete API Key

curl -X DELETE https://api.dnscale.eu/v1/users/{user_id}/apikeys/{key_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Deletion is immediate and revokes all active sessions using that key.

Scopes Reference

Scopes control what operations an API key can perform. Use the principle of least privilege—grant only the scopes required for your use case.

Action scopes and resource boundaries are both enforced. For example, a key needs records:write to change records and its zone_scopes policy must also allow the exact DNS owner name.

Zone and DNS Name Boundaries

Use zone_scopes when an integration should reach only selected zones or record owners:

• record_access: "all" grants normal access to that entire zone, subject to action scopes.
• record_access: "names" grants record access only to the exact names in record_names.
• Names are stored relative to the zone and case-insensitively. Use @ for the zone apex.
• Absolute in-zone names are accepted at creation and returned in relative form.
• * is a literal wildcard DNS owner. It does not match arbitrary labels.
• A names-restricted key can list its parent zone, but it cannot update/delete the zone, manage DNSSEC or zone access, or read zone-level usage.

Record lists are filtered before pagination, so totals and page boundaries describe only records visible to the key. Resource policies are immutable; create and rotate to a new key when the boundary needs to change.

The older zone_ids request field remains compatible and means record_access: "all" for every listed zone. Do not send non-empty zone_ids and zone_scopes together. Omitting both creates a customer-wide key.

Core Resource Scopes

Record, DNSSEC, and zone-usage routes are nested under /v1/zones/{zone_id}/..., so they always need zones:read in addition to their own scope. The dashboard scope picker auto-selects zones:read when you tick any nested scope.

Account Management Scopes

Usage & Billing Scopes

Observability Scopes

DNS traffic alerts also require the dns_traffic_alerts feature entitlement. The feature is enabled by default for Scale and Enterprise plans. See Alerts for route examples and error behavior.

Recommended Scope Sets

DNS Automation (Terraform, Ansible)

["zones:read", "zones:write", "records:read", "records:write"]

ACME DNS-01 Challenge (Let's Encrypt)

["zones:read", "records:read", "records:write"]

Pair those action scopes with a names resource boundary for every challenge owner the client needs. A certificate for example.com uses _acme-challenge; a certificate for api.example.com uses _acme-challenge.api. Exact owner matching means _acme-challenge does not automatically include descendants.

Read-Only Monitoring

["zones:read", "records:read", "usage:read"]

Full Account Management

["zones:read", "zones:write", "records:read", "records:write", "dnssec:read", "dnssec:write", "users:read", "users:write", "apikeys:read", "apikeys:write", "usage:read", "billing:read"]

Security Best Practices

1. Use separate keys for different automation tools and environments
2. Rotate keys regularly - Delete old keys and create new ones periodically
3. Grant minimal scopes - Only include the permissions actually needed
4. Never commit keys to version control
5. Use environment variables or secrets managers to store keys
6. Monitor key usage via the dashboard audit log