Brand domains

A brand can have its own domain, such as brand.example.com. These calls need the brands:domains scope, and the token’s creator must be an owner or admin of the workspace named in X-Workspace-Key. A brand has at most one domain, as in the app.

Connect a domain

PUT /brands/{brand}/domain connects a domain, or replaces the brand’s current one.

curl -X PUT -H "Authorization: Bearer $TARKLE_TOKEN" -H "X-Workspace-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"domain": "brand.example.com"}' \
  https://tarkle.com/api/v1/brands/acme-bank/domain

domain is a plain hostname. A web address, a path, a port or spaces answer 400 invalid_request. Send an international name as punycode (xn--...).

The answer (200) holds:

• status: ownership_verification_required, dns_configuration_required, certificate_pending or active.
• dns_records: the records to add at your DNS host, each with type, host, value, purpose and status. Verification records come first, then routing.
• id, brand_id, domain, certificate_status, last_checked_at and created_at.

Sending the same domain again is safe. When you replace a domain, the new one is attached first and the old one is detached afterwards.

Check the setup

GET /brands/{brand}/domain re-checks the domain with the hosting provider, stores what it finds and returns the same fields. Call it after you add the DNS records, until status is active. provider_unavailable is true when the provider could not be reached; the stored values are returned. 404 not_found means the brand has no domain.

Remove a domain

DELETE /brands/{brand}/domain detaches the domain from hosting and from the brand. The brand page stays. The answer is {"deleted": true, "domain": "..."}.

Plans

The API follows the plan rules of the app. Free workspaces have no brand domain, so a connect call answers 403 forbidden with details.entitlement set to BRAND_PAGE_DOMAIN_LIMIT. Pro and Agency have no limit. A workspace that is at its limit cannot replace a domain either.

Errors

Connecting and removing a domain are recorded in the Activity as brand.domain_set and brand.domain_removed, with the token’s name and the domain.