Skip to main content
PUT
/
apps
/
{client_id}
/
custom-domain
curl -X PUT \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"webDomain":"verify.example.com","oidcDomain":"connect.example.com"}' \
  "https://sandbox.api.hopae.com/connect/v1/apps/abc123/custom-domain"

{
  "webDomain": "verify.example.com",
  "oidcDomain": "connect.example.com",
  "status": "awaiting_dns",
  "requiredAction": "add_cname",
  "statusMessage": "Add the DNS records below, then verify.",
  "dnsRecords": [
    {
      "id": "web-cname",
      "type": "CNAME",
      "host": "verify.example.com",
      "name": "verify.example.com",
      "value": "cname.hopae-edge.com",
      "required": true,
      "description": "Routes your Web Frontend host to the Hopae edge."
    },
    {
      "id": "oidc-cname",
      "type": "CNAME",
      "host": "connect.example.com",
      "name": "connect.example.com",
      "value": "cname.hopae-edge.com",
      "required": true,
      "description": "Routes your OIDC Backend host to the Hopae edge."
    },
    {
      "id": "web-ownership",
      "type": "TXT",
      "host": "verify.example.com",
      "name": "_hopae-verify.verify.example.com",
      "value": "hopae-domain-verification=2b9f8e1c4a7d",
      "required": true,
      "description": "Proves you control the domain."
    }
  ]
}
Sets the two custom hosts and starts provisioning. Returns the CustomDomainStateDto, including the DNS records to add. See Custom Domain for the concept and lifecycle.
This configures one custom domain per app. If a custom domain is already configured, this returns 400 — the error message includes the current status. To change it, delete the existing one first, then configure again.

​
Request

​
Authorization
string
required
Bearer <API_KEY> from Console > Developers > Workspace API Keys.
​
Content-Type
string
application/json

​
Path parameters

​
client_id
string
required
Client identifier of the app.

​
Request body

​
webDomain
string
required
The Web Frontend host (serves the hosted verification UI), e.g. verify.example.com. Host only — no scheme or path.
​
oidcDomain
string
required
The OIDC Backend host (serves the OIDC endpoints), e.g. connect.example.com. Host only — no scheme or path.

​
Response

Returns the updated CustomDomainStateDto. After a successful configure, the status moves to awaiting_dns and the response carries the DNS records to add.
​
webDomain
string
The configured Web Frontend host.
​
oidcDomain
string
The configured OIDC Backend host.
​
status
string
Lifecycle status. One of unconfigured, awaiting_dns, verifying, active, invalid.
​
requiredAction
string
What you need to do next. One of none, add_cname, waiting, verify, contact_support, retry.
​
statusMessage
string
Human-readable explanation of the current status. Omitted when there is nothing to report.
​
dnsRecords
object[]
DNS records to add at your DNS provider. See Get Custom Domain for each record’s fields.
​
lastCheckedAt
string
ISO 8601 timestamp of the most recent verify. Omitted until the first verify runs.
Validation: both hosts are host-only (no https://, no path). They must differ from each other and must share the same base domain (for example, both under example.com).
Configuring only generates the records — it does not verify them. Add all returned DNS records, then call Verify Custom Domain to advance the status.
curl -X PUT \
  -H "Authorization: Bearer sk_workspace_test_..." \
  -H "Content-Type: application/json" \
  -d '{"webDomain":"verify.example.com","oidcDomain":"connect.example.com"}' \
  "https://sandbox.api.hopae.com/connect/v1/apps/abc123/custom-domain"

{
  "webDomain": "verify.example.com",
  "oidcDomain": "connect.example.com",
  "status": "awaiting_dns",
  "requiredAction": "add_cname",
  "statusMessage": "Add the DNS records below, then verify.",
  "dnsRecords": [
    {
      "id": "web-cname",
      "type": "CNAME",
      "host": "verify.example.com",
      "name": "verify.example.com",
      "value": "cname.hopae-edge.com",
      "required": true,
      "description": "Routes your Web Frontend host to the Hopae edge."
    },
    {
      "id": "oidc-cname",
      "type": "CNAME",
      "host": "connect.example.com",
      "name": "connect.example.com",
      "value": "cname.hopae-edge.com",
      "required": true,
      "description": "Routes your OIDC Backend host to the Hopae edge."
    },
    {
      "id": "web-ownership",
      "type": "TXT",
      "host": "verify.example.com",
      "name": "_hopae-verify.verify.example.com",
      "value": "hopae-domain-verification=2b9f8e1c4a7d",
      "required": true,
      "description": "Proves you control the domain."
    }
  ]
}