Multi-account DNS

In production-grade environments, "your Cloudflare account" is rarely a single account. There's a production account holding the customer-facing zones, a staging account holding ephemeral test zones, sometimes a disaster-recovery account that nobody touches except quarterly. CertMate's multi-account support lets one instance manage credentials for all of them and pin each certificate to the right one.

The config shape

The DNS section of CertMate's settings is a two-level dict: provider → account id → credentials. A typical configuration looks like this:

{
  "dns_provider": "cloudflare",
  "default_accounts": {
    "cloudflare": "production",
    "route53": "main-aws"
  },
  "dns_providers": {
    "cloudflare": {
      "production": {
        "name": "Production Environment",
        "api_token": "***masked***"
      },
      "staging": {
        "name": "Staging Environment",
        "api_token": "***masked***"
      }
    },
    "route53": {
      "main-aws": {
        "name": "Main AWS Account",
        "access_key_id": "***masked***",
        "secret_access_key": "***masked***",
        "region": "us-east-1"
      }
    }
  }
}

default_accounts tells CertMate which account to use when a certificate request specifies a provider but not a specific account. Override it per certificate by passing dns_account_id alongside dns_provider.

Adding and managing accounts via API

All four CRUD operations are available on /api/dns/<provider>/accounts:

# Add a new Cloudflare account
curl -X POST http://localhost:8000/api/dns/cloudflare/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "staging",
    "name": "Staging Cloudflare",
    "credentials": { "api_token": "..." }
  }'

# List all accounts for a provider
curl http://localhost:8000/api/dns/cloudflare/accounts \
  -H "Authorization: Bearer $TOKEN"

# Update an account (e.g. rotate token)
curl -X PUT http://localhost:8000/api/dns/cloudflare/accounts/staging \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "credentials": { "api_token": "new-token-here" } }'

# Set staging as the default for Cloudflare
curl -X POST http://localhost:8000/api/dns/cloudflare/default \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "staging" }'

# Delete an account
curl -X DELETE http://localhost:8000/api/dns/cloudflare/accounts/staging \
  -H "Authorization: Bearer $TOKEN"

Pinning a certificate to a specific account

Without a pinned account, CertMate uses the provider's default_accounts entry. To override per-request:

curl -X POST http://localhost:8000/api/certificates/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "ephemeral-test.staging.example.com",
    "dns_provider": "cloudflare",
    "dns_account_id": "staging"
  }'

The certificate metadata stores the pin, so future renewals run through the same account automatically. The audit log records the account id with every issuance and renewal.

Use cases that pay for the complexity

Production / staging separation

The default reason to have multiple accounts. Staging zones get a Cloudflare account with permissions limited to staging-only zones; production gets a separate account with permissions limited to production-only zones. A typo in a staging CertMate config can't modify production DNS — the credentials physically can't reach it.

Per-tenant DNS in a managed-service deployment

If you operate CertMate as a service for multiple internal teams and each team owns its own DNS zone, each team's credentials go in as a separate account. Combined with CertMate's allowed_domains-scoped API keys (v2.5.5+), team A's API token can only issue certificates against domains in team A's Cloudflare account.

Disaster recovery

Keep a DR account in a second provider (Route53 + Cloudflare, say) for the same zone. If your primary provider has an outage that affects DNS API availability, you re-pin the affected certificates to the DR account by hitting /api/certificates/<domain> with a PATCH and CertMate's next renewal cycle uses the new path. This requires the zone to be already loaded on both providers (multi-master DNS); see CNAME delegation for a way to side-step the multi-master complexity entirely.

Blast-radius shrinking

Even with one provider and one zone, two accounts is sometimes the right answer. Account A's token has Zone:DNS:Edit on the apex zone for cert-renewal traffic; account B's token has the same scope but is held by a separate process that never invokes CertMate. If account A's token leaks (CertMate compromise), the attacker can modify DNS records — but account B's records remain unaffected, giving you a clean baseline to compare against during incident response.

Backward compatibility

An older CertMate config with a single-account DNS block migrates to multi-account format on first use. CertMate writes the existing credentials under an auto-generated account_id="default" and sets it as the provider's default. No downtime, no manual migration step. New requests that don't specify dns_account_id route to "default" and keep working.

What's NOT in the multi-account contract

• No automatic failover. If account A is down, CertMate doesn't auto-retry against account B — that's a routing decision, not a credential-store decision, and the right place to solve it is at the request layer (a wrapper that retries with a different dns_account_id) or at the DNS layer (CNAME delegation).
• No per-account rate limit tracking. If you hit a DNS provider's API rate limit on one account, switching to another account doesn't help — you've hit the cap. CertMate's per-provider propagation timings are tuned conservatively to avoid this.
• No credential rotation scheduling. CertMate doesn't rotate your DNS API tokens for you. Rotating Cloudflare/AWS/Azure tokens is your operator workflow; CertMate just stores whatever you upload.

When you're done with multi-account, the next operational concern is usually auto-renewal and key rotation — the long-running discipline of keeping certificates valid without anyone watching.