Choose a custom domain for a kind (client self-serve)
curl --request PUT \
--url https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Brand-Id: <x-brand-id>' \
--data '
{
"hostname": "<string>"
}
'import requests
url = "https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}"
payload = { "hostname": "<string>" }
headers = {
"X-Brand-Id": "<x-brand-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {
'X-Brand-Id': '<x-brand-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({hostname: '<string>'})
};
fetch('https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'hostname' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Brand-Id: <x-brand-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}"
payload := strings.NewReader("{\n \"hostname\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-Brand-Id", "<x-brand-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}")
.header("X-Brand-Id", "<x-brand-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"hostname\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-Brand-Id"] = '<x-brand-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"hostname\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"brand_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"hostname": "<string>",
"kind": "login",
"owner": "platform-walk",
"state": "requested",
"updated_at": "2023-11-07T05:31:56Z",
"bound_by": "<string>",
"cname": {
"name": "<string>",
"type": "CNAME",
"value": "<string>"
},
"live_checks": {
"cert_issued": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
},
"dns_seen": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
},
"login_registered": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
},
"serving": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
}
},
"login_live": {
"certificate": "none",
"checked_at": "2023-11-07T05:31:56Z",
"source": "auth0",
"verification": "pending",
"reason": "not_configured"
},
"records": [
{
"kind": "validation",
"name": "<string>",
"type": "CNAME",
"value": "<string>"
}
]
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}Brand configuration
Choose a custom domain for a kind (client self-serve)
Registers a custom domain for one kind using your own API key: the platform registers it with the auth provider and returns the CNAME record to add to your DNS (state cname_rendered). Idempotent — re-sending the SAME hostname returns the current row unchanged; sending a DIFFERENT hostname for a kind you already registered is a conflict (remove it first). A hostname already claimed by another brand is a conflict (hostnames are globally unique). The brand is the one your key owns (resolved from X-Brand-Id); the brand_id in the path must match it (any mismatch answers 404, never 403).
PUT
/
v1
/
account
/
brands
/
{brand_id}
/
domains
/
{kind}
Choose a custom domain for a kind (client self-serve)
curl --request PUT \
--url https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Brand-Id: <x-brand-id>' \
--data '
{
"hostname": "<string>"
}
'import requests
url = "https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}"
payload = { "hostname": "<string>" }
headers = {
"X-Brand-Id": "<x-brand-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {
'X-Brand-Id': '<x-brand-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({hostname: '<string>'})
};
fetch('https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'hostname' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Brand-Id: <x-brand-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}"
payload := strings.NewReader("{\n \"hostname\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("X-Brand-Id", "<x-brand-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}")
.header("X-Brand-Id", "<x-brand-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"hostname\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.purplelabelmd.com/v1/account/brands/{brand_id}/domains/{kind}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["X-Brand-Id"] = '<x-brand-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"hostname\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"brand_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"hostname": "<string>",
"kind": "login",
"owner": "platform-walk",
"state": "requested",
"updated_at": "2023-11-07T05:31:56Z",
"bound_by": "<string>",
"cname": {
"name": "<string>",
"type": "CNAME",
"value": "<string>"
},
"live_checks": {
"cert_issued": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
},
"dns_seen": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
},
"login_registered": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
},
"serving": {
"checked_at": "2023-11-07T05:31:56Z",
"status": "met",
"reason": "not_configured"
}
},
"login_live": {
"certificate": "none",
"checked_at": "2023-11-07T05:31:56Z",
"source": "auth0",
"verification": "pending",
"reason": "not_configured"
},
"records": [
{
"kind": "validation",
"name": "<string>",
"type": "CNAME",
"value": "<string>"
}
]
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>"
}Authorizations
Per-client API key (M2M). Presented as Authorization: Bearer <key>.
Headers
Your brand id (brd_...). It must be one of the brands your API key's account owns; with a publishable key it must be the one brand the key was issued for. A missing or malformed value is refused with 400, and an unknown or foreign brand with 404.
Pattern:
^brd_[A-Za-z0-9][A-Za-z0-9_-]*$Send a unique value on every write. Do not assume that a repeated request with the same key is de-duplicated unless the operation says so.
Path Parameters
the brand whose custom domains to view or manage (must match X-Brand-Id).
Pattern:
^brd_[A-Za-z0-9][A-Za-z0-9_-]*$the custom-domain kind — login (the auth domain) or member (the member-portal domain).
Available options:
login, member Body
application/json
Choose a custom domain for a kind. The only field is the hostname you want to use; the brand is the one your API key owns (resolved from X-Brand-Id, never taken from the body), so a request-supplied brand or provider id is structurally inert. Any other field is refused with a 400 that names it — a field this operation does not accept is never silently ignored.
the custom hostname to register (e.g. login.example.com).
Minimum string length:
1Response
the registered row + its CNAME paste-row (state cname_rendered)
One custom-domain row as the registry holds it: the brand, the kind (login | member), the hostname, its provisioning state, who owns and who bound the host, timestamps, and the CNAME paste-row to add to your DNS. The row never carries a secret nor the provider's internal domain id. An absent row (a kind you have not registered) is the shared-domain default.
Show child attributes
Show child attributes