Skip to main content

DNS Providers

Connect your DNS provider for automatic domain verification and certificate management.

Project Settings

Overview​

DNS provider integration enables:

  • Automatic domain verification - DNS-01 challenges for SSL certificates
  • Wildcard certificates - Secure all subdomains
  • Faster verification - No manual DNS record creation
  • Real-time status monitoring - Track synchronization and detect issues instantly

Supported Providers​

ProviderAPI SupportWildcard Certs
Cloudflare✓✓
AWS (Route 53)✓✓
DigitalOcean✓✓
OVH✓✓
Gandi✓✓
GoDaddy✓✓
Azure DNS✓✓
IONOS✓✓
Scaleway✓✓

Adding a DNS Provider​

Steps​

  1. Go to your project
  2. Click Settings in the project sidebar
  3. Select the DNS Providers tab
  4. Click Add Provider
  5. Select your provider
  6. Enter API credentials
  7. Click Save

Provider Configuration​

Cloudflare​

Required credentials:

  • API Token (recommended) or
  • Global API Key + Email

Creating an API Token:

  1. Go to Cloudflare Dashboard
  2. Click Create Token
  3. Use template: Edit zone DNS
  4. Select your zone
  5. Create and copy token
Token: <your-cloudflare-api-token>

Permissions needed:

  • Zone → DNS → Edit
  • Zone → Zone → Read

Optional settings:

  • Enable Cloudflare Proxy - Route traffic through Cloudflare's CDN and security features

AWS (Route 53)​

Required credentials:

  • Access Key ID
  • Secret Access Key

IAM Policy:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"route53:GetChange",
"route53:ChangeResourceRecordSets",
"route53:ListResourceRecordSets"
],
"Resource": [
"arn:aws:route53:::hostedzone/ZONE_ID",
"arn:aws:route53:::change/*"
]
},
{
"Effect": "Allow",
"Action": "route53:ListHostedZones",
"Resource": "*"
}
]
}

DigitalOcean​

Required credentials:

  • Personal Access Token

Creating Token:

  1. Go to DigitalOcean API
  2. Generate new token
  3. Grant: Read and Write
Token: <your-digitalocean-token>

OVH​

Required credentials:

  • Application Key
  • Application Secret
  • Consumer Key

Creating an OVH API Token:

  1. Go to OVH API Token Creation
  2. Fill in the application details:
    • Application name: SailOps DNS Management (or your preferred name)
    • Application description: DNS management for SailOps custom domains
  3. Set the required API permissions (rights):
MethodPathDescription
GET/domain/zoneList available zones
GET/domain/zone/*/recordList DNS records in a zone
GET/domain/zone/*/record/*Get specific record details
PUT/domain/zone/*/record/*Update existing DNS records
POST/domain/zone/*/recordCreate new DNS records
DELETE/domain/zone/*/record/*Remove DNS records
GET/domain/zone/*/soaGet SOA record information
POST/domain/zone/*/refreshApply DNS changes

Copy-paste format for easy OVH API token creation:

GET    /domain/zone
GET /domain/zone/*/record
GET /domain/zone/*/record/*
PUT /domain/zone/*/record/*
POST /domain/zone/*/record
DELETE /domain/zone/*/record/*
GET /domain/zone/*/soa
POST /domain/zone/*/refresh
  1. Set Validity: Choose your preferred duration (e.g., "Unlimited" for permanent access)
  2. Click Create keys
  3. Copy the generated credentials:
    • Application Key (AK)
    • Application Secret (AS)
    • Consumer Key (CK)

Important Notes:

  • These permissions are the minimum required for SailOps to manage DNS records
  • The * wildcard allows access to all your domain zones
  • You can restrict access to specific zones by replacing * with your domain name (e.g., /domain/zone/example.com/record)
  • Keep your credentials secure and never share them publicly

Gandi​

Required credentials:

  • API Key (Personal Access Token)

Creating Token:

  1. Go to Gandi Account
  2. Security → Personal Access Tokens
  3. Create with DNS permissions

Azure DNS​

Required credentials:

  • Subscription ID
  • Tenant ID
  • Client ID
  • Client Secret
  • Resource Group Name

Creating Service Principal:

az ad sp create-for-rbac \
--name "SailOps-DNS" \
--role "DNS Zone Contributor" \
--scopes /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Network/dnszones/{zone}

Getting Resource Group Name:

The Resource Group Name is the name of the Azure Resource Group containing your DNS Zone. You can find it in the Azure Portal under your DNS Zone's overview page.

GoDaddy​

Required credentials:

  • API Key
  • API Secret

Getting Credentials:

  1. Go to GoDaddy Developer Portal
  2. Create an API Key
  3. Select Production environment
  4. Copy API Key and Secret

IONOS​

Required credentials:

  • API Key

Getting Credentials:

  1. Go to IONOS Developer Portal
  2. Navigate to API Keys section
  3. Create a new API key with DNS permissions
  4. Copy the API key

Scaleway​

Required credentials:

  • Access Key (API Key)
  • Secret Key

Getting Credentials:

  1. Go to Scaleway Console
  2. Navigate to IAM → API Keys
  3. Create a new API key
  4. Copy Access Key and Secret Key

Using DNS Providers​

Domain Verification​

When adding a custom domain:

  1. SailOps detects matching DNS provider
  2. Automatically creates verification records
  3. Requests SSL certificate
  4. Cleans up temporary records

Without DNS Provider​

If no provider is configured:

  1. Manual DNS record creation required
  2. HTTP-01 challenge used (no wildcards)
  3. Longer verification time

Managing Providers​

Viewing Providers​

  1. Go to Settings in the project sidebar
  2. Select the DNS Providers tab
  3. See all configured providers and managed zones

Testing Connection​

  1. Click Test on a provider
  2. SailOps verifies API access
  3. Lists accessible zones

Updating Credentials​

  1. Click on the provider
  2. Update API credentials
  3. Click Save

Removing a Provider​

  1. Click Delete
  2. Confirm removal
caution

Removing a provider doesn't affect existing certificates but prevents automatic renewal.

Provider Status Monitoring​

SailOps provides real-time status monitoring for your DNS providers, helping you quickly identify and resolve configuration issues.

Status Indicators​

Each DNS provider displays a status badge indicating its current state:

StatusBadgeDescription
Healthy🟢 GreenProvider is working correctly. DNS records are being synchronized.
Syncing🔵 BlueProvider is starting up or currently synchronizing records.
Error🔴 RedProvider has encountered an error. Check the error details for more information.

Status Information​

When you view a DNS provider, you'll see:

  • Status Badge - Current synchronization state
  • Last Sync Time - When the provider last attempted to synchronize
  • Last Successful Sync - When records were last successfully updated
  • Managed Records Count - Number of DNS records currently managed

Error Types​

When a provider encounters an error, SailOps categorizes it to help you troubleshoot:

Error CodeDescriptionCommon Causes
Authentication FailedAPI credentials are invalid or expiredInvalid API key, expired token, revoked access
Permission DeniedCredentials lack required permissionsMissing DNS edit permissions, zone access restricted
Rate LimitedToo many API requestsHigh frequency of DNS changes, provider rate limits
Network ErrorCannot connect to provider APIProvider outage, connectivity issues, TLS/certificate errors
API ErrorProvider API returned an errorProvider service issues (500, 502, 503, 504 errors)
Configuration ErrorProvider configuration is invalidZone not found, invalid zone configuration, domain mismatch

Resolving Status Issues​

Authentication Failed​

  1. Verify your API credentials are correct
  2. Check if credentials have expired or been revoked
  3. Regenerate credentials from your DNS provider's dashboard
  4. Update credentials in SailOps

Permission Denied​

  1. Review the required permissions for your provider (see Provider Configuration)
  2. Update your API credentials to include necessary permissions
  3. For limited-scope credentials, ensure they have access to the correct zones

Rate Limited​

  1. Wait for the rate limit window to reset (usually 1-5 minutes)
  2. If persistent, reduce the frequency of domain changes
  3. Consider consolidating domains under wildcard certificates

Network Error​

  1. Check if your DNS provider is experiencing an outage
  2. Verify the provider's API endpoint is accessible
  3. If using TLS/certificates, ensure they are valid

Configuration Error​

  1. Verify the domain zone exists in your DNS provider
  2. Check that the zone name matches exactly
  3. Ensure your API credentials have access to the specific zone

Automatic Recovery​

SailOps automatically attempts to recover from transient errors:

  • Network errors: Retried automatically with exponential backoff
  • Rate limits: Requests are throttled and retried after the limit resets
  • API errors: Retried for temporary server issues (5xx errors)

For persistent errors (authentication, permissions, configuration), manual intervention is required.

Zone Management​

Automatic Zone Detection​

SailOps automatically detects zones when:

  • Domain matches provider zone
  • API has zone access

Multiple Zones​

One provider can manage multiple zones:

Zone Conflicts​

If multiple providers manage the same zone:

  • First matching provider is used
  • Order in settings determines priority

Security Best Practices​

1. Minimal Permissions​

Create dedicated credentials with limited scope:

✓ Only DNS read/write access
✓ Only specific zones
✓ Dedicated service account

✗ Admin/Owner access
✗ All zones access
✗ Shared credentials

2. Credential Rotation​

Rotate API credentials regularly:

  • Every 90 days recommended
  • After team member changes
  • After security incidents

3. Audit Logging​

Monitor DNS changes:

  • Review provider audit logs
  • Set up alerts for unexpected changes
  • Track certificate issuance

Troubleshooting​

tip

Check the Provider Status indicator first! The status badge and error details often provide immediate insight into the problem. See Provider Status Monitoring for details.

Verification Failed​

Error: DNS verification timeout

  1. Check provider credentials are valid
  2. Verify zone is accessible
  3. Check for DNS propagation (wait 5-10 minutes)

Error: Zone not found

  1. Verify domain matches zone exactly
  2. Check API has access to zone
  3. Ensure zone exists in provider

Error: Permission denied

  1. Review API permissions
  2. Add missing scopes
  3. Recreate credentials if needed

Certificate Issues​

Error: CAA record prevents issuance

Add CAA record for Let's Encrypt:

example.com. CAA 0 issue "letsencrypt.org"

Error: Rate limit exceeded

Let's Encrypt limits:

  • 50 certificates per domain per week
  • 5 duplicate certificates per week

Solutions:

  1. Wait for rate limit reset
  2. Use wildcard certificates
  3. Consolidate subdomains

Provider-Specific Issues​

Cloudflare: Proxy conflict

Disable Cloudflare proxy (orange cloud) for verification:

  1. SailOps creates records with proxy disabled
  2. After verification, you can enable proxy

AWS: Region mismatch

Route 53 is global, but ensure:

  1. Correct AWS region in credentials
  2. Hosted zone ID matches domain