OpenProvider Skill#

OpenProvider (openprovider.eu) is the domain registrar and DNS provider for Atlas Frontline. This skill handles all domain, DNS, SSL, and customer handle operations via the OpenProvider REST API v1beta.

Auth Flow#

Always obtain a token before making any API call.

1. Load credentials: OPENPROVIDER_USERNAME / OPENPROVIDER_PASSWORD (env vars), with legacy fallback from OPENPROVIDER_USER / OPENPROVIDER_PASS, or DB table system_settings (key: integration_credentials_openprovider)
2. Get token: POST https://api.openprovider.eu/v1beta/auth/login
3. Use token as Authorization: Bearer {token} header
4. Token valid for 48h (Atlas caches for 24h)
5. On HTTP 401: invalidate token → re-authenticate → retry request

bash

# Get token
OP_USER="${OPENPROVIDER_USERNAME:-${OPENPROVIDER_USER:-}}"
OP_PASS="${OPENPROVIDER_PASSWORD:-${OPENPROVIDER_PASS:-}}"
TOKEN=$(curl -s -X POST https://api.openprovider.eu/v1beta/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "'"$OP_USER"'", "password": "'"$OP_PASS"'"}' \
  | jq -r '.data.token')

→ Full auth docs: references/auth.md

API Base#

SettingValueBase URLhttps://api.openprovider.eu/v1beta/AuthBearer TokenContent-Typeapplication/jsonTimeout30sRetries3 (backoff: 1s, 3s, 9s)

Routing Matrix#

Use this table to find the right action and reference file:

Domain Operations#

RequestEndpointMethodReferenceIs domain available? / Check domain/domains/checkPOSTdomains.mdRegister / buy domain/domainsPOSTdomains.mdGet domain status/domains/{id}GETdomains.mdList all domains/domainsGETdomains.mdRenew domain/domains/{id}/renewPOSTdomains.mdUpdate domain settings/domains/{id}PUTdomains.mdTransfer domain/domains/transferPOSTdomains.mdDelete / cancel domain/domains/{id}DELETEdomains.mdRestore domain/domains/{id}/restorePOSTdomains.md

DNS Operations#

RequestEndpointMethodReferenceCreate DNS zone/dns/zonesPOSTdns.mdGet DNS zone/dns/zones/{domain}GETdns.mdAdd/remove DNS records/dns/zones/{domain}PUTdns.mdList DNS records/dns/zones/{domain}/recordsGETdns.mdDelete DNS zone/dns/zones/{domain}DELETEdns.mdList all DNS zones/dns/zonesGETdns.md

SSL Operations#

RequestEndpointMethodReferenceOrder SSL certificate/ssl/ordersPOSTssl.mdList SSL certificates/ssl/ordersGETssl.mdGet SSL certificate details/ssl/orders/{id}GETssl.mdReissue SSL certificate/ssl/orders/{id}/reissuePOSTssl.mdRenew SSL certificate/ssl/orders/{id}/renewPOSTssl.mdCancel SSL certificate/ssl/orders/{id}DELETEssl.mdList SSL products/prices/ssl/productsGETssl.md

Nameserver Operations#

RequestEndpointMethodReferenceList NS groups/dns/nameservers/groupsGETnameservers.mdGet NS group details/dns/nameservers/groups/{name}GETnameservers.mdCreate NS group/dns/nameservers/groupsPOSTnameservers.mdUpdate NS group/dns/nameservers/groups/{name}PUTnameservers.mdDelete NS group/dns/nameservers/groups/{name}DELETEnameservers.md

TLD Information#

RequestEndpointMethodReferenceList all TLDs/tldsGETtlds.mdGet TLD details & prices/tlds/{name}GETtlds.md

Customers & Resellers#

RequestEndpointMethodReferenceList customers/customersGETcustomers-resellers.mdGet customer/customers/{handle}GETcustomers-resellers.mdCreate customer / handle/customersPOSTcustomers-resellers.mdUpdate customer/customers/{handle}PUTcustomers-resellers.mdDelete customer/customers/{handle}DELETEcustomers-resellers.mdReseller info/resellers/{id}GETcustomers-resellers.md

Workflow: Register Domain (End-to-End)#

Full flow when a user says "register the domain example.com":

1. Check availability → POST /domains/check with with_price: true
2. Ensure customer handle → GET /customers or POST /customers
3. Register domain → POST /domains with owner_handle, ns_group
4. Create DNS zone → POST /dns/zones
5. Set DNS records → PUT /dns/zones/{domain} (A, MX, SPF, DKIM, DMARC)
6. Check status → GET /domains/{id}

Workflow: Change DNS Record#

1. Load current records → GET /dns/zones/{domain}/records
2. Normalize the record name to zone-relative form
3. Remove old record → PUT /dns/zones/{domain} with records.remove
4. Add new record → PUT /dns/zones/{domain} with records.add
5. Verify the resulting record names → GET /dns/zones/{domain}/records

Important: Do NOT combine remove and add in a single PUT call! Two separate calls required (Error 817).

DNS Record Naming Rule (CRITICAL)#

When updating records in zone /dns/zones/{domain}, OpenProvider expects the record name in zone-relative form for subdomains.

Use:

• phone for phone.example.com in zone example.com
• _dmarc for _dmarc.example.com in zone example.com
• www for www.example.com in zone example.com

Do NOT use the full FQDN as name when writing records inside a zone unless you have verified OpenProvider expects it for that exact operation.

If you send phone.example.com as name inside zone example.com, OpenProvider may append the zone again and create the wrong record:

• intended: phone.example.com
• accidental result: phone.example.com.example.com

Safe Name Normalization#

Before any DNS write:

1. Identify the zone apex, e.g. example.com
2. Convert requested host to zone-relative label:
   • example.com → apex/root ( "" empty string for OpenProvider zone writes, not the full domain, and not @ unless explicitly verified)
   • phone.example.com → phone
   • _dmarc.example.com → _dmarc
3. Read back the zone records after the write and confirm the final record name is correct

Apex / Root Record Rule (CRITICAL)#

For OpenProvider PUT /dns/zones/{domain} writes, the zone apex must be sent as an empty string name:

json

{
  "name": "",
  "type": "TXT",
  "value": "google-site-verification=...",
  "ttl": 600
}

Do not send the full domain name as name for apex writes inside the zone payload. If you send example.com as name while writing inside zone example.com, OpenProvider may create:

• intended: example.com
• accidental result: example.com.example.com

Also do not assume @ works for OpenProvider. It may be rejected as an invalid record name.

Safe DNS Change Pattern#

For any add/replace of a record:

1. Read current zone records
2. Check whether the target record already exists
3. If replacing, remove conflicting record first
4. Add the new record using the zone-relative name
5. Re-read the zone and verify the exact final FQDN
6. Optionally check public resolution separately ( dig) because provider acceptance ≠ public propagation

MX / Mail Provider Rule (CRITICAL)#

For OpenProvider DNS writes, MX records use the field name prio, not priority.

Correct example for a mail subdomain inside zone example.com:

json

{
  "records": {
    "add": [
      {
        "name": "send",
        "type": "MX",
        "value": "feedback-smtp.eu-west-1.amazonses.com",
        "ttl": 600,
        "prio": 10
      }
    ]
  }
}

Do not use priority in the payload unless you have verified a different endpoint/schema.

For Resend/Amazon SES sender domains, a known-good public result is:

bash

dig +short MX send.example.com
# 10 feedback-smtp.eu-west-1.amazonses.com.

Example#

Zone: example.com

Correct add payload for phone.example.com:

json

{
  "records": {
    "add": [
      {
        "name": "phone",
        "type": "A",
        "value": "46.225.220.40",
        "ttl": 900
      }
    ]
  }
}

Incorrect payload:

json

{
  "records": {
    "add": [
      {
        "name": "phone.example.com",
        "type": "A",
        "value": "46.225.220.40",
        "ttl": 900
      }
    ]
  }
}

That incorrect payload can create phone.example.com.example.com.

Apex TXT example for example.com:

Correct:

json

{
  "records": {
    "add": [
      {
        "name": "",
        "type": "TXT",
        "value": "google-site-verification=...",
        "ttl": 600
      }
    ]
  }
}

Incorrect:

json

{
  "records": {
    "add": [
      {
        "name": "example.com",
        "type": "TXT",
        "value": "google-site-verification=...",
        "ttl": 600
      }
    ]
  }
}

That incorrect payload can create example.com.example.com.

Workflow: Domain Transfer#

1. Get auth code from current registrar (EPP/transfer code)
2. Ensure customer handle → POST /customers if needed
3. Initiate transfer → POST /domains/transfer with auth_code + owner_handle

Error Handling#

All API responses follow this structure:

json

{"code": 0, "desc": "...", "data": {...}}

• code: 0 = success
• code: != 0 = error (details in desc)
• HTTP 401 = token expired → re-authenticate
• HTTP 429 = rate limit → wait and retry
• If env lookup fails, check whether the instance still uses legacy names OPENPROVIDER_USER / OPENPROVIDER_PASS

Common errors:

CodeMeaningSolution817Duplicate DNS recordRemove existing record first, then add new one816Validation error / invalid field valueRe-check record schema; for MX use prio instead of priority801Domain already existsDomain is already registered899Rate limitReduce batch size, wait1000Auth failedCheck credentials

→ Full error reference: references/auth.md

Atlas Integration (Context)#

OpenProvider is integrated into Atlas via the Frontline module:

• Service: api/services/frontline/openprovider.ts — API client
• DNS: api/services/frontline/dns.ts — DNS configuration & verification
• Handles: api/services/frontline/handles.ts — Workspace handle management
• Search: api/services/frontline/domain-search.ts — Domain availability search
• Domains: api/services/frontline/domains.ts — Domain lifecycle
• Types: shared/types/frontline.ts — TypeScript definitions
• Credentials: system_settings table, key integration_credentials_openprovider

Key Limits#

LimitValueDomain check batch sizeMax 5 per requestSuggestions per searchMax 20Token validity48h (cache: 24h)Request timeout30sDNS TTL minimum600sDomain registrations per workspace/dayMax 3 (Atlas limit)

Reference Files#

FileContentsreferences/auth.mdAuthentication, tokens, credentials, error handlingreferences/domains.mdDomain CRUD, check, transfer, renew, restorereferences/dns.mdDNS zones & records (CRUD, patterns, pitfalls)references/ssl.mdSSL certificates (order, reissue, renew, cancel)references/nameservers.mdNameserver group managementreferences/tlds.mdTLD information & pricingreferences/customers-resellers.mdCustomer handles & reseller info