Skip to content

Domains and email

The addresses your dedicated environment answers on, how to move it to a domain of your own, and how it sends e-mail — through the platform or your own server.

Your environment answers on two host names: one for the API and the hosted sign-in pages, which is also the issuer of every token, and one for the console. Configuration → Domain shows the addresses in use and where they come from, and is where you move the environment to a domain of your own.

Addresses in use

SourceAddressesWhen
Hosting provider addressOne address per service on the hosting provider’s domain.Every environment has them. They are used while there is no other.
Platform subdomainauth.<name>.<platform domain> and console.<name>.<platform domain>Created during provisioning where the platform has a domain for environments.
Your domainTwo host names of yours, such as auth.acme.com and console.acme.com.Once you activate it.

Your own domain, once active, wins over the platform subdomain, which wins over the hosting provider’s addresses. The <name> of a platform subdomain comes from your account’s name — lowercase letters, digits and dashes, up to 24 characters — with a number added when another environment already holds it.

The API address is where every realm’s issuer lives. With auth.acme.com active, the issuer of realm acme is:

IssuerPlain text
https://auth.acme.com/realms/acme

Using your own domain

You need two host names under the same domain — auth.acme.com and console.acme.com under acme.com — because passkeys are bound to the domain both share. They must be different from each other and not under the platform’s own domain. One domain of your own can be registered at a time, and the environment must be ready.

  1. Add the domain

    In Configuration → Domain, under Your own domain, enter the host for the API and sign-in pages and the host for the console — host names only, without https:// or a path — and choose Add domain.

  2. Create the DNS records

    The page lists every record to create at your DNS provider, with its name, type and value to copy: a routing record for each host — usually a CNAME — and, when the hosting provider asks for one, a TXT record that proves the host is yours. For example:

    NameTypeValue
    auth.acme.comCNAMEAs shown in the console
    console.acme.comCNAMEAs shown in the console
    _railway-verify.auth.acme.comTXTAs shown in the console
    _railway-verify.console.acme.comTXTAs shown in the console

    Each record turns Found when DNS answers with the expected value, or Needs update when it answers with another one. The page checks again every 30 seconds.

  3. Wait for the certificates

    Once a host’s records answer, a certificate is issued for it, which can take from a few minutes to a few hours. When both certificates are issued, the domain reads Ready to activate.

  4. Activate the domain

    Choose Activate domain when the applications integrated with the current address are ready to move. The API and the console are redeployed with the new addresses, and the domain reads In use.

Using Cloudflare?

Set these records to DNS only. A proxied record answers with Cloudflare’s address instead of the expected value, so it is never found and the certificate is never issued.
StateWhat it means
Waiting for DNSThe domain is registered; its records or certificates are not in place yet. Nothing changes for your users.
Ready to activateBoth certificates were issued. The environment still answers at its current addresses until you activate.
In useThe environment answers on your domain.

What activating changes

  • The issuer moves to the new API address. Tokens signed under the old issuer stop being valid, so everyone signed in signs in again.
  • Applications integrated with the old address must be updated to the new issuer, or their sign-ins fail.
  • Passkeys are bound to the domain they were registered on, so passkeys registered on the previous addresses are not offered on the new ones; people register them again.
  • The DNS records must stay in place: deleting them takes the environment off these addresses.
Activating or removing a domain writes the environment’s configuration again, and that includes the default e-mail sender (EMAIL_FROM_NAME, EMAIL_FROM_ADDRESS) and the platform’s EMAIL_MAILERSEND_APIKEY. If you changed how the environment sends e-mail, check Variables afterwards and apply your changes again.

Removing your domain

Remove domain forgets the domain. If it was in use, the environment goes back to the platform subdomain — or to the hosting provider’s address where there is none — and the API and the console are redeployed. The issuer changes back too, so everyone signs in again and integrated applications must be pointed back at that address. The records at your DNS provider stay until you delete them.

How the environment sends e-mail

Your environment sends e-mail for password recovery, sign-in codes and invitations, among others. It starts out sending through the platform’s own MailerSend account and sender, so password recovery works from the first minute — including the e-mailed renewal administrators of the authio realm use when their password expires.

For each e-mail, the environment uses the first transport that is configured:

  1. A MailerSend or SendGrid key set in the e-mail settings of the client the e-mail belongs to.
  2. EMAIL_MAILERSEND_APIKEY on the environment — the platform’s key by default.
  3. Your SMTP server, from the EMAIL_SMTP_* variables.

SMTP is therefore used only once EMAIL_MAILERSEND_APIKEY is removed.

Sending from your own e-mail

  1. Open the e-mail variables

    In Configuration → Variables, find the E-mail group. Only an owner or administrator of the account can change it.

  2. Set the sender

    Set EMAIL_FROM_NAME and EMAIL_FROM_ADDRESS to the name and address your e-mails should come from. The address must be one your server is allowed to send for.

  3. Fill in your SMTP server

    Set EMAIL_SMTP_HOST, EMAIL_SMTP_PORT (usually 587, or 465 for SSL), EMAIL_SMTP_USERNAME, EMAIL_SMTP_PASSWORD and EMAIL_SMTP_ENABLESSL.

  4. Remove the platform’s key

    Choose Remove on EMAIL_MAILERSEND_APIKEY. While it is set, MailerSend wins over SMTP.

  5. Save and check

    Choose Save and redeploy. The API is redeployed with the new settings within a few minutes; then request a password recovery for your own user to see an e-mail arrive.

To keep MailerSend with your own account instead, replace EMAIL_MAILERSEND_APIKEY with your key and set EMAIL_FROM_ADDRESS to an address on a domain verified in that MailerSend account.

Do not leave the environment without a working transport. Without e-mail, password recovery fails, and administrators of the authio realm must change their password in the console before it expires.

Next steps

Operations and monitoringEvery variable you can change, and how saving redeploys the API.Any OIDC clientPoint an application at a new issuer after a domain change.PasskeysHow passkeys are registered and offered at sign-in.Provisioning and lifecycleWhat recreating or removing the environment deletes, your own domain included.