Updated
Custom domains
Every tenant is served at https://<slug>.algizian.com. If you would rather have people sign in on your own domain, for example login.example.com, add it to the tenant. You do this with one API call and one DNS record, and the certificate is issued for you.
What you can use
A subdomain of a domain you control: login.example.com, id.example.com, auth.shop.example.co.uk. A bare apex such as example.com is not possible, because an apex cannot hold a CNAME record. Lowercase names only.
Refused: IP addresses, local and private names, names under shared hosting or tunnel domains where you do not control DNS (for example pages.dev or github.io), domains that belong to well-known brands, and domains that belong to algizian.
Add the domain
curl -s -X PUT https://id.algizian.com/api/v1/tenants/acme-games/domain \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "hostname": "login.example.com" }'
The answer shows the domain's state and the record you need:
{
"slug": "acme-games",
"issuer": "https://acme-games.algizian.com",
"customDomain": {
"hostname": "login.example.com",
"status": "pending",
"dns": { "type": "CNAME", "name": "login.example.com", "target": "cname.algizian.com" },
"issuer": "https://login.example.com"
}
}
Create the CNAME
At your DNS provider create:
| Type | Name | Target |
|---|---|---|
CNAME | login (or login.example.com, depending on your provider) | cname.algizian.com |
Check the status
Call POST /tenants/{tenant}/domain/refresh (or the refresh_custom_domain tool over MCP) until customDomain.status is active; GET /tenants/{tenant} shows the same state.
| Status | Meaning |
|---|---|
pending | The domain is registered, but the DNS record is not seen yet or the certificate is not issued yet. Nothing is served on it. |
active | The record is in place and the certificate is issued. The domain serves sign-in. |
error | Something went wrong and error says what. Fix it, then refresh again, or register the domain again. |
The certificate is issued automatically once the CNAME resolves; no certificate request and no file to upload. This usually takes a few minutes after the DNS change is visible and can take up to an hour. While it is pending, customDomain.sslStatus shows how far the certificate is. If you use a CAA record at your DNS provider, it must allow the certificate authority, or issuance stays pending; remove the CAA record or ask support which authority to allow.
Until the domain is active, the host is not served: opening it in a browser shows a certificate or not-found error, and its discovery document does not exist. That is expected.
What your users see
People are sent to https://login.example.com/authorize (or the address in the discovery document), see the sign-in screen with your branding on your own domain, and come back to your app from that host. The address bar never shows algizian.
- With the shared Google, Microsoft or Apple app the provider's consent screen names algizian, and the user is passed through a short step on an algizian address before returning to your domain. With your own provider app the consent screen shows your name and the provider returns straight to your domain: add
https://login.example.com/cb/<provider>as a redirect URI in your app registration too (the answer that sets your credentials lists it once the domain isactive; see your own provider apps). - A signed-in session belongs to the host it was created on. Someone signed in on
acme-games.algizian.comis asked to sign in again onlogin.example.com.
One issuer per host
Each host is its own issuer. A token issued on login.example.com has iss of https://login.example.com, and your app must validate it against that issuer. Pick one host for each application and use only that one in its configuration; a tenant has one custom domain at a time.
What changes
Both addresses keep working. The discovery document on login.example.com lists endpoints on that host, and the one on acme-games.algizian.com keeps its own. Both use the same signing keys and the same users, so a person is the same user on either host.
When you switch your app to the custom domain, change its issuer in your OIDC library configuration and in the places where you validate tokens: a token issued on one host is not valid for the other issuer. Use the discovery document at https://login.example.com/.well-known/openid-configuration as the single source of endpoints.
Remove the domain
DELETE /tenants/{tenant}/domain removes it. Registering a different hostname replaces the current one. The tenant keeps its <slug>.algizian.com address. Remove the CNAME at your DNS provider afterwards. A domain that another tenant already uses answers 409.