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.

Customer Context

Your API key automatically provides customer context. You don't need to specify a customer ID in API requests—the system determines your customer from the authenticated key.

Creating API Keys

Via the Dashboard

Navigate to DNScale Dashboard → Settings → API Keys
Click Create API Key
Enter a name and select the required scopes
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": "Terraform Automation",
    "scopes": ["zones:read", "zones:write", "records:read", "records:write"]
  }'

Response:

{
  "status": "success",
  "data": {
    "id": "key_abc123",
    "name": "Terraform Automation",
    "key": "dnscale_live_xxxxxxxxxxxxxxxxxxxx",
    "scopes": ["zones:read", "zones:write", "records:read", "records:write"],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Store Securely

The API key is only returned once. Store it securely in a secrets manager or environment variable.

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.

Core Resource Scopes

Scope	Grants
`zones:read`	List and view DNS zones
`zones:write`	Create, update, and delete DNS zones
`records:read`	List and view DNS records
`records:write`	Create, update, and delete DNS records
`dnssec:read`	View DNSSEC status and keys
`dnssec:write`	Enable/disable DNSSEC, manage cryptographic keys

Account Management Scopes

Scope	Grants
`users:read`	List and view team members
`users:write`	Create, update, and delete users
`apikeys:read`	List and view API keys
`apikeys:write`	Create and delete API keys
`customers:read`	View customer account details
`customers:write`	Update customer account settings

Usage & Billing Scopes

Scope	Grants
`usage:read`	View usage statistics
`billing:read`	View billing summaries and history
`alerts:read`	View usage alerts
`alerts:write`	Create, update, and delete alerts

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"]

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

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

Authentication