Documentation

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:

TypeNameTarget
CNAMElogin (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.

StatusMeaning
pendingThe domain is registered, but the DNS record is not seen yet or the certificate is not issued yet. Nothing is served on it.
activeThe record is in place and the certificate is issued. The domain serves sign-in.
errorSomething 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 is active; see your own provider apps).
  • A signed-in session belongs to the host it was created on. Someone signed in on acme-games.algizian.com is asked to sign in again on login.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.