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

# 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

Routing Matrix

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

Domain Operations

DNS Operations

SSL Operations

Nameserver Operations

TLD Information

Customers & Resellers

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:

{
  "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:

{
  "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:

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:

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

Incorrect payload:

{
  "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:

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

Incorrect:

{
  "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:

{"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:

→ 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

Reference Files