docs(inconsistent naming): custom domain (#10377)

# Which Problems Are Solved partially #9342 # How the Problems Are Solved Name custom domain consistently in the docs according to https://github.com/zitadel/zitadel/issues/5888 # Additional Changes # Additional Context
2026-08-18 17:05:03 -05:00 · 2025-09-03 13:23:01 +00:00
parent a1ad87387d
commit 7f27efcac1
47 changed files with 144 additions and 143 deletions
@@ -87,7 +87,7 @@ The authentication API (aka Auth API) is used for all operations on the currentl
 #### GRPC

 Endpoint:
-$ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/
+`${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/`

 Definition:
 [Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto)
@@ -95,7 +95,7 @@ Definition:
 #### REST

 Endpoint:
-$ZITADEL_DOMAIN/auth/v1/
+`${CUSTOM_DOMAIN}/auth/v1/`

 API Reference:
 [OpenAPI Docs](/apis/resources/auth)
@@ -120,7 +120,7 @@ To identify the current organization you can send a header `x-zitadel-orgid` or
 #### GRPC

 Endpoint:
-$ZITADEL_DOMAIN/zitadel.management.v1.ManagementService/
+`${CUSTOM_DOMAIN}/zitadel.management.v1.ManagementService/`

 Definition:
 [Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto)
@@ -128,7 +128,7 @@ Definition:
 #### REST

 Endpoint:
-$ZITADEL_DOMAIN/management/v1/
+`${CUSTOM_DOMAIN}/management/v1/`

 API Reference:
 [OpenAPI Docs](/apis/resources/mgmt)
@@ -151,7 +151,7 @@ This API is intended to configure and manage one ZITADEL instance itself.
 #### GRPC

 Endpoint:
-$ZITADEL_DOMAIN/zitadel.admin.v1.AdminService/
+`${CUSTOM_DOMAIN}/zitadel.admin.v1.AdminService/`

 Definition:
 [Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto)
@@ -159,7 +159,7 @@ Definition:
 #### REST

 Endpoint:
-$ZITADEL_DOMAIN/admin/v1/
+`${CUSTOM_DOMAIN}/admin/v1/`

 API Reference:
 [OpenAPI Docs](/apis/resources/admin)
@@ -184,7 +184,7 @@ Checkout the guide how to [access the ZITADEL System API](/docs/guides/integrate
 #### GRPC

 Endpoint:
-$ZITADEL_DOMAIN/zitadel.system.v1.SystemService/
+`${CUSTOM_DOMAIN}/zitadel.system.v1.SystemService/`

 Definition:
 [System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
@@ -192,7 +192,7 @@ Definition:
 #### REST

 Endpoint:
-$ZITADEL_DOMAIN/system/v1/
+`${CUSTOM_DOMAIN}/system/v1/`

 API Reference:
 [OpenAPI Docs](/apis/resources/system)
@@ -215,7 +215,7 @@ The Assets API allows you to up- and download all kinds of assets. This can be f
 #### REST

 Endpoint:
-$ZITADEL_DOMAIN/assets/v1/
+`${CUSTOM_DOMAIN}/assets/v1/`

 Definition:
 [Assets](./assets/assets.md)
@@ -271,14 +271,14 @@ In the table below you can see the URI of those calls.

 | Service | URI                                                   |
 | :------ | :---------------------------------------------------- |
-| REST    | $ZITADEL_DOMAIN/auth/v1/users/me                      |
-| GRPC    | $ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/GetMyUser |
+| REST    | `${CUSTOM_DOMAIN}/auth/v1/users/me`                      |
+| GRPC    | `${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/GetMyUser` |

 ## Domains

-ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your custom domain `$ZITADEL_DOMAIN`
+ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your custom domain `${CUSTOM_DOMAIN}`

-The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Console UI, which you'll find under `{your_domain}/ui/console/`.
+The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Console UI, which you'll find under `${CUSTOM_DOMAIN}/ui/console/`.

 Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](/docs/self-hosting/manage/custom-domain).

@@ -24,7 +24,7 @@ Not all request parameters are available in the playground. Please refer to the

 ### Your Domain

-The <span className="text-yellow-500">Instance Domain</span> to your ZITADEL instance. Use the base-path, the playground will add the required path to the request.
+The <span className="text-yellow-500">Custom Domain</span> to your ZITADEL instance. Use the base-path, the playground will add the required path to the request.

 ### Required Parameters

@@ -12,13 +12,13 @@ import TokenExchangeTypes from "./_token_exchange_types.mdx";
 ## OpenID Connect 1.0 Discovery

 The OpenID Connect Discovery Endpoint is located within the issuer domain.
-This would give us `{your_domain}/.well-known/openid-configuration`.
+This would give us `${CUSTOM_DOMAIN}/.well-known/openid-configuration`.

 **Link to spec.** [OpenID Connect Discovery 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-discovery-1_0.html)

 ## authorization_endpoint

-`{your_domain}/oauth/v2/authorize`
+`${CUSTOM_DOMAIN}/oauth/v2/authorize`

 :::note
 The authorization_endpoint is located with the login page, due to the need of accessing the same cookie domain
@@ -172,7 +172,7 @@ the error will be display directly to the user on the auth server

 ## token_endpoint

-`{your_domain}/oauth/v2/token`
+`${CUSTOM_DOMAIN}/oauth/v2/token`

 The token_endpoint will as the name suggests return various tokens (access, id and refresh) depending on the used `grant_type`.
 When using [`authorization_code`](#authorization-code-grant-code-exchange) flow call this endpoint after receiving the code from the authorization_endpoint.
@@ -262,7 +262,7 @@ Send a client assertion as JWT for us to validate the signature against the regi

 ```BASH
 curl --request POST \
-  --url {your_domain}/oauth/v2/token \
+  --url ${CUSTOM_DOMAIN}/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data assertion=eyJhbGciOiJSUzI1Ni...
@@ -360,7 +360,7 @@ Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on ho

 ```BASH
 curl --request POST \
-  --url {your_domain}/oauth/v2/token \
+  --url ${CUSTOM_DOMAIN}/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic ${BASIC_AUTH}' \
  --data grant_type=client_credentials \
@@ -376,7 +376,7 @@ Or you can also send your `client_id` and `client_secret` as parameters in the b

 ```BASH
 curl --request POST \
-  --url {your_domain}/oauth/v2/token \
+  --url ${CUSTOM_DOMAIN}/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=${CLIENT_ID} \
@@ -472,7 +472,7 @@ Send a `client_assertion` as JWT for us to validate the signature against the re

 ## introspection_endpoint

-`{your_domain}/oauth/v2/introspect`
+`${CUSTOM_DOMAIN}/oauth/v2/introspect`

 This endpoint enables clients to validate an `acccess_token`, either opaque or JWT. Unlike client side JWT validation,
 this endpoint will check if the token is not revoked (by client or logout).
@@ -497,7 +497,7 @@ Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Se

 ```BASH
 curl --request POST \
-  --url {your_domain}/oauth/v2/introspect \
+  --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {your_basic_auth_header}' \
  --data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...
@@ -516,7 +516,7 @@ Send a `client_assertion` as JWT for us to validate the signature against the re

 ```BASH
 curl --request POST \
-  --url {your_domain}/oauth/v2/introspect \
+  --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data client_assertion=eyJhbGciOiJSUzI1Ni... \
@@ -555,7 +555,7 @@ If the authorization fails, an HTTP 401 with `invalid_client` will be returned.

 ## userinfo_endpoint

-`{your_domain}/oidc/v1/userinfo`
+`${CUSTOM_DOMAIN}/oidc/v1/userinfo`

 This endpoint will return information about the authorized user.

@@ -563,7 +563,7 @@ Send the `access_token` of the **user** (not the client) as Bearer Token in the

 ```BASH
 curl --request GET \
-  --url {your_domain}/oidc/v1/userinfo
+  --url ${CUSTOM_DOMAIN}/oidc/v1/userinfo
  --header 'Authorization: Bearer dsfdsjk29fm2as...'
 ```

@@ -578,7 +578,7 @@ If the token is invalid or expired, an HTTP 401 will be returned.

 ## revocation_endpoint

-`{your_domain}/oauth/v2/revoke`
+`${CUSTOM_DOMAIN}/oauth/v2/revoke`

 This endpoint enables clients to revoke an `access_token` or `refresh_token` they have been granted.

@@ -638,7 +638,7 @@ Send a `client_assertion` as JWT for ZITADEL to verify the signature against the

 ```BASH
 curl --request POST \
-  --url {your_domain}/oauth/v2/revoke \
+  --url ${CUSTOM_DOMAIN}/oauth/v2/revoke \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data client_assertion=eyJhbGciOiJSUzI1Ni... \
@@ -650,7 +650,7 @@ curl --request POST \

 ## end_session_endpoint

-`{your_domain}/oidc/v1/end_session`
+`${CUSTOM_DOMAIN}/oidc/v1/end_session`

 The endpoint has to be opened in the user agent (browser) to terminate the user sessions.

@@ -672,7 +672,7 @@ If neither an `id_token_hint` nor a `client_id` parameter is provided, the `post

 ## jwks_uri

-`{your_domain}/oauth/v2/keys`
+`${CUSTOM_DOMAIN}/oauth/v2/keys`

 The endpoint returns a JSON Web Key Set (JWKS) containing the public keys that can be used to locally validate JWTs you received from ZITADEL.
 The alternative would be to validate tokens with the [introspection endpoint](#introspection_endpoint).
@@ -11,7 +11,7 @@ deprovisioning.
 ## Supported endpoints

 The Zitadel SCIM v2.0 service provider implementation supports the following endpoints.
-The base URL for the SCIM endpoint in Zitadel is: `https://${ZITADEL_DOMAIN}/scim/v2/{orgId}`.
+The base URL for the SCIM endpoint in Zitadel is: `https://${CUSTOM_DOMAIN}/scim/v2/{orgId}`.

 | Endpoint                                                                | Remarks                                                    |
 |-------------------------------------------------------------------------|------------------------------------------------------------|
@@ -122,7 +122,7 @@ https://github.com/zitadel/zitadel-go/blob/next/example/app/templates/profile.ht
 ### Start your application

 You will need to provide some values for the program to run:
- `domain`: Your ZITADEL instance domain, e.g. my-domain.zitadel.cloud
+- `domain`: Your ZITADEL custom domain, e.g. my-domain.zitadel.cloud
 - `key`: Random secret string. Used for symmetric encryption of state parameters, cookies and PCKE.
 - `clientID`: The clientID provided by ZITADEL
 - `redirectURI`: The redirectURI registered at ZITADEL
@@ -375,7 +375,7 @@ OIDC_CLIENT_ID="248680248240075805@dev"
 OIDC_CLIENT_SECRET="BJPhEJULSUXseC4geqg5Yg4wWMoy7RgZKar86mbIpt8ZekC5kixMzYGcXLDeeJv7"
 ```

-> The well-known URL needs to be adjusted to your own instance domain.
+> The well-known URL needs to be adjusted to your own custom domain.

 Activate the route that is used as callback by the OIDC bundle:

@@ -98,7 +98,7 @@ https://github.com/zitadel/zitadel-go/blob/next/example/api/http/main.go
 ```

 You will need to provide some values for the program to run:
- `domain`: Your ZITADEL instance domain, e.g. https://my-domain.zitadel.cloud
+- `domain`: Your ZITADEL custom domain, e.g. https://my-domain.zitadel.cloud
 - `key`: The path to the downloaded key.json
 - `port`: The port on which the API will be accessible, default it 8089

@@ -179,10 +179,11 @@ class ZitadelIntrospectTokenValidator(IntrospectTokenValidator):
        res = self.introspect_token(*args, **kwargs)
        return res
 ```
-3. Create a new file named ".env" in the directory. Copy the configuration in the [".env.example"](https://github.com/zitadel/example-api-python3-flask/blob/main/.env.example) file to the newly created .env file. Set the values with your Instance Domain/Issuer URL, Client ID, and Client Secret from the previous steps. Obtain your Issuer URL by following [these steps](/docs/guides/start/quickstart#referred1).
+
+3. Create a new file named ".env" in the directory. Copy the configuration in the [".env.example"](https://github.com/zitadel/example-api-python3-flask/blob/main/.env.example) file to the newly created .env file. Set the values with your Custom Domain/Issuer URL, Client ID, and Client Secret from the previous steps. Obtain your Issuer URL by following [these steps](/docs/guides/start/quickstart#referred1).

 ```python
-ZITADEL_DOMAIN = "https://your-domain-abcdef.zitadel.cloud"
+ZITADEL_DOMAIN = "https://custom-domain-abcdef.zitadel.cloud"
 CLIENT_ID = "197....@projectname"
 CLIENT_SECRET = "NVAp70IqiGmJldbS...."
 ```
@@ -1,6 +1,6 @@
 1. Go to the Settings
-    - To allow external IdP logins by default, go to your instance default settings at `$YOUR-DOMAIN/ui/console/instance?id=general`
-    - To allow external IdP logins on an organization, go to `$YOUR-DOMAIN/ui/console/org-settings?id=login` and ensure you have the right org context.
+    - To allow external IdP logins by default, go to your instance default settings at `${CUSTOM_DOMAIN}/ui/console/instance?id=general`
+    - To allow external IdP logins on an organization, go to `${CUSTOM_DOMAIN}/ui/console/org-settings?id=login` and ensure you have the right org context.
 2. Modify your login policy in the menu "Login Behavior and Security"
 3. Enable the attribute "External Login allowed"

@@ -85,8 +85,8 @@ In ZITADEL, you have the flexibility to link an external Identity Provider (IdP)
 The login policy can be set as a default at the instance level and can be customized for each organization. The configuration process varies slightly depending on your focus:


- **For default settings**, navigate to: `$YOUR-DOMAIN/ui/console/instance?id=general`
- **For specific organization settings**, select the organization from the menu and visit: `$YOUR-DOMAIN/ui/console/org-settings?id=login`
+- **For default settings**, navigate to: `${CUSTOM_DOMAIN}/ui/console/instance?id=general`
+- **For specific organization settings**, select the organization from the menu and visit: `${CUSTOM_DOMAIN}/ui/console/org-settings?id=login`


 Once in the settings:
@@ -23,7 +23,7 @@ import TestSetup from './_test_setup.mdx';
 2. Add your App Name, your Company Page and a Logo
 3. Add "Sign In with LinkedIn using OpenID Connect" by clicking "Request access"
 4. Go to the Auth Settings of the App and add the following URL to the "Authorized redirect URLs"
- - `{your_domain}/ui/login/login/externalidp/callback`
+ - `${CUSTOM_DOMAIN}/ui/login/login/externalidp/callback`
 - Example redirect url for the domain `https://acme.zitadel.cloud` would look like this:  `https://acme.zitadel.cloud/ui/login/login/externalidp/callback`
 5. Verify the app as your company
 6. In the Auth - OAuth 2.0 scopes section you should see `openid`, `profile` and `email` listed
@@ -8,7 +8,7 @@ Request Example:

 ```bash
 curl --request GET \
-  --url https://$ZITADEL_DOMAIN/v2/settings/login \
+  --url https://${CUSTOM_DOMAIN}/v2/settings/login \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''
 ```
@@ -16,7 +16,7 @@ Make sure that the provided token is from the authenticated user, resp. the mana

 ```bash
 curl --request DELETE \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/218480890961985793 \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/218480890961985793 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json'
@@ -28,7 +28,7 @@ Send the session token in the body of the request:

 ```bash
 curl --request DELETE \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/218480890961985793 \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/218480890961985793 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -9,7 +9,7 @@ The list of session IDs can be sent in the “search sessions” request to get

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/search \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -8,7 +8,7 @@ Example Request:

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/218480890961985793 \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/218480890961985793 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -76,7 +76,7 @@ With the user_code entered by the user you will now be able to get the informati

 ```bash
 curl --request GET \
-  --url https://$ZITADEL_DOMAIN/v2/oidc/device_authorization/FWRK-JGWK \
+  --url https://${CUSTOM_DOMAIN}/v2/oidc/device_authorization/FWRK-JGWK \
  --header 'Authorization: Bearer '"$TOKEN"''
 ```

@@ -122,7 +122,7 @@ Read more about the [Authorize or Deny Device Authorization Request Documentatio
 Make sure that the authorization header is from an account which is permitted to finalize the Auth Request through the `IAM_LOGIN_CLIENT` role.
 ```bash
 curl --request POST \
-  --url $ZITADEL_DOMAIN/v2/oidc/device_authorization/XzNejv6NxqVU8Qur5uxEh7f_Wi1p0qUu4PJTJ6JUIx0xtJ2uqmU \
+  --url ${CUSTOM_DOMAIN}/v2/oidc/device_authorization/XzNejv6NxqVU8Qur5uxEh7f_Wi1p0qUu4PJTJ6JUIx0xtJ2uqmU \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -142,7 +142,7 @@ If the user denies the device authorization request, you can deny the request by

 ```bash
 curl --request POST \
-  --url $ZITADEL_DOMAIN/v2/oidc/device_authorization/ \
+  --url ${CUSTOM_DOMAIN}/v2/oidc/device_authorization/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -27,7 +27,7 @@ In the response, you will get an authentication URL of the provider you like.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/idp_intents \
+  --url https://${CUSTOM_DOMAIN}/v2/idp_intents \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -49,7 +49,7 @@ curl --request POST \
 		"changeDate": "2023-06-14T12:51:29.654819Z",
 		"resourceOwner": "163840776835432705"
 	},
-	"authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F$ZITADEL_DOMAIN%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617"
+	"authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F${CUSTOM_DOMAIN}%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617"
 }
 ```

@@ -59,13 +59,13 @@ The next step is to call the auth URL you got in the response from the previous
 This will open up the login page of the given provider. In this guide, it is Google Login.

 ```bash
-https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F$ZITADEL_DOMAIN%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617
+https://accounts.google.com/o/oauth2/v2/auth?client_id=Test&prompt=select_account&redirect_uri=https%3A%2F%2F${CUSTOM_DOMAIN}%2Fidps%2Fcallback&response_type=code&scope=openid+profile+email&state=218525066445455617
 ```

 After the user has successfully authenticated, a redirect to the ZITADEL backend /idps/callback will automatically be performed.

 :::warning
-Note that the redirect URL is `https://{YOUR-DOMAIN}/idps/callback` when using the new V2 hosted login compared to the V1 hosted login, which was `https://{YOUR-DOMAIN}/ui/login/login/externalidp/callback`.
+Note that the redirect URL is `https://${CUSTOM_DOMAIN}/idps/callback` when using the new V2 hosted login compared to the V1 hosted login, which was `https://${CUSTOM_DOMAIN}/ui/login/login/externalidp/callback`.
 :::

 ## Get Provider Information
@@ -79,7 +79,7 @@ To get the information of the provider, make a request to ZITADEL.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/idp_intents/$INTENT_ID \
+  --url https://${CUSTOM_DOMAIN}/v2/idp_intents/$INTENT_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -138,7 +138,7 @@ This check requires that the previous step ended on the successful page and didn

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\

@@ -170,7 +170,7 @@ The display name is used to list the linkings on the users.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/human \
+  --url https://${CUSTOM_DOMAIN}/v2/users/human \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -209,7 +209,7 @@ If you want to link/connect to an existing account you can perform the add ident

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/users/218385419895570689/links \
+  --url https://${CUSTOM_DOMAIN}/v2/users/users/218385419895570689/links \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -41,7 +41,7 @@ Request Example:

 ```bash
 curl --request POST \
-    --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/totp \
+    --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/totp \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer '"$TOKEN"''
    --header 'Content-Type: application/json' \
@@ -73,7 +73,7 @@ Request Example:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/totp/verify \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/totp/verify \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''
  --header 'Content-Type: application/json' \
@@ -99,7 +99,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -136,7 +136,7 @@ More detailed information about the API: [Update session Documentation](/apis/re
 Example Request
 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/$SESSION-ID \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/$SESSION-ID \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
@@ -175,7 +175,7 @@ Example Request:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/phone \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/phone \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -195,7 +195,7 @@ More detailed information about the API: [Verify phone](/apis/resources/user_ser
 Example Request:
 ```bash
 curl --request POST \
-    --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/phone/verify \
+    --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/phone/verify \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer '"$TOKEN"'' \
    --header 'Content-Type: application/json' \
@@ -213,7 +213,7 @@ More detailed information about the API: [Add OTP SMS for a user](/apis/resource
 Example Request:
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/otp_sms \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/otp_sms \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json'
@@ -237,7 +237,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -264,7 +264,7 @@ Example Request

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/225307381909694507 \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/225307381909694507 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -301,7 +301,7 @@ More detailed information about the API: [Add OTP Email for a user](/apis/resour
 Example Request:
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER-ID/otp_email \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER-ID/otp_email \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json'
@@ -325,7 +325,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -352,7 +352,7 @@ Example Request

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/225307381909694507 \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/225307381909694507 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -386,7 +386,7 @@ Request Example:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/u2f \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/u2f \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''
  --header 'Content-Type: application/json' \
@@ -457,7 +457,7 @@ Example Request:
 ```bash

 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/u2f/$PASSKEY_ID \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/u2f/$PASSKEY_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -497,7 +497,7 @@ Example Request

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -510,7 +510,7 @@ curl --request POST \
  "metadata": {},
  "challenges": {
 		"webAuthN": {
-			"domain": "YOUR-Domain",
+			"domain": "CUSTOM_DOMAIN",
 			"userVerificationRequirement": "USER_VERIFICATION_REQUIREMENT_DISCOURAGED"
 		}
 	}
@@ -55,7 +55,7 @@ With the ID from the redirect before you will now be able to get the information

 ```bash
 curl --request GET \
-  --url https://$ZITADEL_DOMAIN/v2/oidc/auth_requests/V2_224908753244265546 \
+  --url https://${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \
  --header 'Authorization: Bearer '"$TOKEN"''
 ```

@@ -100,7 +100,7 @@ Read more about the [Finalize Auth Request Documentation](/docs/apis/resources/o
 Make sure that the authorization header is from an account which is permitted to finalize the Auth Request through the `IAM_LOGIN_CLIENT` role.
 ```bash
 curl --request POST \
-  --url $ZITADEL_DOMAIN/v2/oidc/auth_requests/V2_224908753244265546 \
+  --url ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -34,7 +34,7 @@ Send either the sendLink or the returnCode (empty message) in the request body,

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/passkeys/registration_link \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/passkeys/registration_link \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -81,7 +81,7 @@ The code only has to be filled if the user did get a registration code.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/passkeys \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/passkeys \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -185,7 +185,7 @@ Example Request:

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/passkeys/$PASSKEY_ID \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/passkeys/$PASSKEY_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -223,7 +223,7 @@ More detailed information about the API: [Create Session Documentation](/apis/re
 Example Request:
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -29,7 +29,7 @@ Make sure to also include the URL Template to customize the reset link in the em

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/password_reset \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password_reset \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -48,7 +48,7 @@ Send the request with asking for the return Code in the body of the request.
 #### Request
 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/password_reset \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password_reset \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -96,7 +96,7 @@ In this case it requires additionally the current password instead of the verifi

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/$USER_ID/password \
+  --url https://${CUSTOM_DOMAIN}/v2/users/$USER_ID/password \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -55,7 +55,7 @@ With the ID from the redirect before you will now be able to get the information

 ```bash
 curl --request GET \
-  --url https://$ZITADEL_DOMAIN/v2/saml/saml_requests/V2_224908753244265546 \
+  --url https://${CUSTOM_DOMAIN}/v2/saml/saml_requests/V2_224908753244265546 \
  --header 'Authorization: Bearer '"$TOKEN"''
 ```

@@ -97,7 +97,7 @@ Read more about the [Finalize SAML Request Documentation](/docs/apis/resources/s
 Make sure that the authorization header is from an account which is permitted to finalize the SAML Request through the `IAM_LOGIN_CLIENT` role.
 ```bash
 curl --request POST \
-  --url $ZITADEL_DOMAIN/v2/saml/saml_requests/V2_224908753244265546 \
+  --url ${CUSTOM_DOMAIN}/v2/saml/saml_requests/V2_224908753244265546 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -23,7 +23,7 @@ Read more about the metadata [here](/docs/guides/manage/customize/user-metadata)

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/users/human \
+  --url https://${CUSTOM_DOMAIN}/v2/users/human \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -111,7 +111,7 @@ Send it to the Get Session Endpoint to find out how the user has authenticated.

 ```bash
 curl --request POST \
-  --url https://$ZITADEL_DOMAIN/v2/sessions \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"'' \
  --header 'Content-Type: application/json' \
@@ -176,7 +176,7 @@ To update an existing session, add the session ID you got in the previous step t

 ```bash
 curl --request PATCH \
-  --url https://$ZITADEL_DOMAIN/v2/sessions/$SESSION_ID \
+  --url https://${CUSTOM_DOMAIN}/v2/sessions/$SESSION_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer '"$TOKEN"''\
  --header 'Content-Type: application/json' \
@@ -180,7 +180,7 @@ Your contributions will play a crucial role in shaping the future of our login s

 #### Step-by-step Guide

-**Trying out the new login:** To preview the new login without changing your current setup, the easiest way is to visit `https://<YOUR_ZITADEL_INSTANCE_DOMAIN>/ui/v2/login` on your Zitadel Cloud instance domain. You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication.
+**Trying out the new login:** To preview the new login without changing your current setup, the easiest way is to visit `https://<CUSTOM_DOMAIN>/ui/v2/login` on your Zitadel Cloud custom domain. You can also activate the v2 login for your apps, so users are redirected to `/ui/v2/login` for authentication.

 **Customizing the new login:** The easiest way to actually customizing it is to fork the https://github.com/zitadel/typescript repo and use the "Deploy" button to run your code on Vercel.

@@ -202,7 +202,7 @@ Your contributions will play a crucial role in shaping the future of our login s
        The simplest way to deploy the new login for yourself is by using the [“Deploy” button in our repository](https://github.com/zitadel/typescript?tab=readme-ov-file#deploy-to-vercel) to deploy the login directly to your Vercel.

        1. [Create a service user](https://zitadel.com/docs/guides/integrate/service-users/personal-access-token#create-a-service-user-with-a-pat) with a PAT in your instance
-        2. Give the user IAM_LOGIN_CLIENT Permissions in the default settings (YOUR_DOMAIN/ui/console/instance?id=organizations)
+        2. Give the user IAM_LOGIN_CLIENT Permissions in the default settings (CUSTOM_DOMAIN/ui/console/instance?id=organizations)
        Note: [Zitadel Manager Guide](https://zitadel.com/docs/guides/manage/console/managers)
        3. Deploy login to Vercel: You can do so by directly clicking the [“Deploy” button](https://github.com/zitadel/typescript?tab=readme-ov-file#deploy-to-vercel) at the bottom of the readme in our [repository](https://github.com/zitadel/typescript)
        4. If you have used the deploy button in the steps before, you will automatically be asked for this step. Enter the environment variables in Vercel
@@ -226,7 +226,7 @@ Your contributions will play a crucial role in shaping the future of our login s
 As this feature is currently in Beta, please be aware of some potential workarounds and important considerations before implementation.

 - **Create Users:** The new typescript login is built with the session and the user V2 API, the users V2 API does have some differences to the v1 API, so make sure you create users through the new API.
- **External IDPs:** If you want to use external identity provider login, such as Login with Google or Apple. You can follow our existing setup guides, just make sure to use the following redirect url: $YOUR-DOMAIN/idps/callback
+- **External IDPs:** If you want to use external identity provider login, such as Login with Google or Apple. You can follow our existing setup guides, just make sure to use the following redirect url: `${CUSTOM_DOMAIN}/idps/callback`
 - **Passkey/U2F:** Those authentication methods are bound to a domain. As your new login runs on a different domain than the previous login, existing passwordless authentication and u2f (fingerprint, face id, etc.) can’t be used. Also when they are managed through the management console of ZITADEL, they are added on a different domain.
  <br />
  *Note: If you run the login on a subdomain of your current instance, this problem
@@ -60,7 +60,7 @@ So check [Client Secret Basic Auth Method](/apis/openidoauth/authn-methods#clien

 ```curl
 curl --request POST \
--url {your-domain}/oauth/v2/token \
+--url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Authorization: Basic ${basic}' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
@@ -62,7 +62,7 @@ for us to validate the signature against the registered public key:

 ```curl
 curl --request POST \
--url {your-domain}/oauth/v2/token \
+--url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
@@ -67,7 +67,7 @@ Send your `client_id` and the previously generated string as `code_verifier` for

 ```curl
 curl --request POST \
--url {your-domain}/oauth/v2/token \
+--url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
@@ -53,7 +53,7 @@ Send your `client_id` and the previously generated string as `code_verifier` for

 ```curl
 curl --request POST \
--url {your-domain}/oauth/v2/token \
+--url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
@@ -296,7 +296,7 @@ Next month, Key ID 6 will be activated, an new key added and Key ID 2 can be del
 ## JSON web key set

 The JSON web key set (JWKS) endpoint serves all available public keys for the instance on
-`{your_domain}/oauth/v2/keys`. This includes activated, newly non-activated and deactivated web keys. The response format is defined in [RFC7517, section 5: JWK Set Format](https://www.rfc-editor.org/rfc/rfc7517#section-5).
+`${CUSTOM_DOMAIN}/oauth/v2/keys`. This includes activated, newly non-activated and deactivated web keys. The response format is defined in [RFC7517, section 5: JWK Set Format](https://www.rfc-editor.org/rfc/rfc7517#section-5).

 And looks like:

@@ -83,7 +83,7 @@ Alternatively, you can include the claims `urn:iam:org:project:roles` or/and `ur

 ### Retrieve roles from the userinfo endpoint

-The user info endpoint is  **$CUSTOM-DOMAIN/oidc/v1/userinfo**.
+The user info endpoint is  **`${CUSTOM_DOMAIN}`/oidc/v1/userinfo**.

 This endpoint will return information about the authenticated user.
 Send the access token of the user as `Bearer Token` in the `Authorization` header:
@@ -91,7 +91,7 @@ Send the access token of the user as `Bearer Token` in the `Authorization` heade
 **cURL Request:**
 ```bash
 curl --request GET \
- --url $CUSTOM-DOMAIN/oidc/v1/userinfo
+ --url ${CUSTOM_DOMAIN}/oidc/v1/userinfo
 --header 'Authorization: Bearer <TOKEN>'
 ```

@@ -208,7 +208,7 @@ https://github.com/zitadel/actions/blob/main/examples/custom_roles.js
 ### Retrieve roles using the auth API

 Now we will use the auth API to retrieve roles from a logged in user using the user’s token
-The base URL is: **https://$ZITADEL_DOMAIN/auth/v1**
+The base URL is: **https://`${CUSTOM_DOMAIN}`/auth/v1**

 Let’s start with a user who has multiple roles in different organizations in a multi-tenanted set up. You can use the logged in user’s token or the machine user’s token to retrieve the authorizations using the [APIs listed under user authorizations/grants in the auth API](/docs/apis/resources/auth/user-authorizations-grants). 

@@ -219,11 +219,11 @@ Let’s start with a user who has multiple roles in different organizations in a

 Returns a list of roles for the authenticated user and for the requesting project (based on the token).

-**URL: https://$CUSTOM-DOMAIN/auth/v1/permissions/me/_search**
+**URL: https://`${CUSTOM_DOMAIN}`/auth/v1/permissions/me/_search**

 **cURL request:** 
 ```bash
-curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/permissions/me/_search' \
+curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/permissions/me/_search' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer <TOKEN>'
 ```
@@ -244,12 +244,12 @@ Returns a list of permissions the authenticated user has in ZITADEL based on the

 This request can be used if you are building a management UI. For instance, if the UI is managing users, you can show the management functionality based on the permissions the user has. Here’s an example: if the user has `user.read` and `user.write` permission you can show the edit buttons, if the user only has `user.read` permission, you can hide the edit buttons.

-**URL: https://$CUSTOM-DOMAIN/auth/v1/permissions/zitadel/me/_search**
+**URL: https://`${CUSTOM_DOMAIN}`/auth/v1/permissions/zitadel/me/_search**

 **cURL Request:** 

 ```bash
-curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/permissions/zitadel/me/_search' \
+curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/permissions/zitadel/me/_search' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer <TOKEN>'
 ```
@@ -290,12 +290,12 @@ curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/permissions/zitadel/me/_search'

 Returns a list of user grants the authenticated user has. User grants consist of an organization, a project and roles.

-**URL: https://$CUSTOM-DOMAIN/auth/v1/usergrants/me/_search**
+**URL: https://`${CUSTOM-DOMAIN}`/auth/v1/usergrants/me/_search**

 **cURL request:**

 ```bash
-curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/usergrants/me/_search' \
+curl -L -X POST 'https://${CUSTOM_DOMAIN}/auth/v1/usergrants/me/_search' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer <TOKEN>' \
@@ -392,7 +392,7 @@ curl -L -X POST 'https://$CUSTOM-DOMAIN/auth/v1/usergrants/me/_search' \
 ### Retrieve roles using the management API
 Now we will use the management API to retrieve user roles under an admin user. 

-The base URL is: **https://$CUSTOM-DOMAIN/management/v1**
+The base URL is: **https://`${CUSTOM_DOMAIN}`/management/v1**

 In [APIs listed under user grants in the management API](/docs/apis/resources/mgmt/user-grants), you will see that you can use the management API to retrieve and modify user grants. The two API paths that we are interested in to fetch user roles are given below.

@@ -402,12 +402,12 @@ In [APIs listed under user grants in the management API](/docs/apis/resources/mg

 Returns a list of user roles that match the search queries. A user with manager permissions will call this API and will also have to reside in the same organization as the user. 

-**URL: https://$CUSTOM-DOMAIN/management/v1/users/grants/_search**
+**URL: https://`${CUSTOM_DOMAIN}`/management/v1/users/grants/_search**

 **cURL request:** 

 ```bash
-curl -L -X POST 'https://$CUSTOM-DOMAIN/management/v1/users/grants/_search' \
+curl -L -X POST 'https://${CUSTOM_DOMAIN}/management/v1/users/grants/_search' \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer <TOKEN>' \
@@ -471,12 +471,12 @@ curl -L -X POST 'https://$CUSTOM-DOMAIN/management/v1/users/grants/_search' \

 Returns a user grant per ID. A user grant is a role a user has for a specific project and organization.

-**URL: https://$ZITADEL_DOMAIN//management/v1/users/:userId/grants/:grantId**
+**URL: https://`${CUSTOM_DOMAIN}`/management/v1/users/:userId/grants/:grantId**

 **cURL request:**

 ```bash 
-curl -L -X GET 'https://$ZITADEL_DOMAIN/management/v1/users/:userId/grants/:grantId' \
+curl -L -X GET 'https://${CUSTOM_DOMAIN}/management/v1/users/:userId/grants/:grantId' \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer <TOKEN>'
 ```
@@ -28,7 +28,7 @@ In Authentication > Enterprise
 1. Press the "+" button right to "OpenID Connect"  
  ![Create new connection](/img/oidc/auth0/auth0-create-app.png)
 2. Set a connection name for example "ZITADEL"
-3. The issuer url is `https://<YOUR_DOMAIN>/.well-known/openid-configuration`
+3. The issuer url is `https://${CUSTOM_DOMAIN}/.well-known/openid-configuration`
 4. Copy the callback URL (ending with `/login/callback`)

 The configuration should look like this:
@@ -30,7 +30,7 @@ Cloudflare will return an error "User email was not returned. API permissions ar

 1. On the Cloudflare dashboard go to Zero Trust, click settings, and then select "Authentication"
 2. Add a new login method with the type "OpenID Connect"
-3. Fill in the required information. Check the discovery endpoint of your instance `https://{your_domain}/.well-known/openid-configuration` for the urls. As mentioned in the Cloudflare docs the Certificate Url is jwks_uri.
+3. Fill in the required information. Check the discovery endpoint of your instance `https://${CUSTOM_DOMAIN}/.well-known/openid-configuration` for the urls. As mentioned in the Cloudflare docs the Certificate Url is jwks_uri.
 4. Disable PKCE (Cloudflare requires a client secret for PKCE, which is currently not supported)
 5. Add the following claims: "openid", "profile", "email"
 6. Test the connection
@@ -42,9 +42,9 @@ Cloudflare will return an error "User email was not returned. API permissions ar
  "config": {
    "client_id": "<your client id>",
    "client_secret": "<your client secret>",
-    "auth_url": "https://{your_domain}.zitadel.cloud/oauth/v2/authorize",
-    "token_url": "https://{your_domain}.zitadel.cloud/oauth/v2/token",
-    "certs_url": "https://{your_domain}.zitadel.cloud/oauth/v2/keys",
+    "auth_url": "https://${CUSTOM_DOMAIN}.zitadel.cloud/oauth/v2/authorize",
+    "token_url": "https://${CUSTOM_DOMAIN}.zitadel.cloud/oauth/v2/token",
+    "certs_url": "https://${CUSTOM_DOMAIN}.zitadel.cloud/oauth/v2/keys",
    "scopes": ["openid", "email", "profile"],
    "pkce_enabled": false,
  },
@@ -36,12 +36,12 @@ gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "ZITADEL",
-    icon: "https://<YOUR_DOMAIN>/ui/console/assets/icons/favicon-32x32.png",
+    icon: "https://${CUSTOM_DOMAIN}/ui/console/assets/icons/favicon-32x32.png",
    args: {
      name: "openid_connect",
      scope: ["openid","profile","email"],
      response_type: "code",
-      issuer: "https://<YOUR_DOMAIN>",
+      issuer: "https://${CUSTOM_DOMAIN}",
      discovery: true,
      client_options: {
        identifier: "<CLIENT ID from ZITADEL>",
@@ -33,25 +33,25 @@ Open the Google settings for [SSO with third-party IdP](https://admin.google.com

 ![SSO with third-party IdP](/img/guides/integrate/services/google-workspace-sso-overview.png)

-Download the public certificate from your ZITADEL instance by requesting `$YOUR_DOMAIN/saml/v2/certificate`
+Download the public certificate from your ZITADEL instance by requesting `${CUSTOM_DOMAIN}/saml/v2/certificate`

 ```bash
- wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt
+ wget ${CUSTOM_DOMAIN}/saml/v2/certificate -O idp.crt
 ```

-Always replace `$YOUR_DOMAIN` with your instance domain.
+Always replace `${CUSTOM_DOMAIN}` with your custom domain.

 Use the following configuration

 | Setting | Value |
 | --- | --- |
 | Set up SSO with third-party identity provider | Enable (check) |
-| Sign-in page URL | $YOUR_DOMAIN/saml/v2/SSO |
-| Sign-out page URL | $YOUR_DOMAIN/saml/v2/SLO |
+| Sign-in page URL | `${CUSTOM_DOMAIN}`/saml/v2/SSO |
+| Sign-out page URL | `${CUSTOM_DOMAIN}`/saml/v2/SLO |
 | Verification Certificate | Upload the certificate (idp.crt) |
 | Use a domain-specific issuer | Enable (check) |
 | Network masks | Leave blank|
-| Change password URL | $YOUR_DOMAIN/ui/console/users/me?id=security |
+| Change password URL | `${CUSTOM_DOMAIN}`/ui/console/users/me?id=security |

 ### Create a SAML application in ZITADEL

@@ -125,7 +125,7 @@ Download the public certificate from your ZITADEL instance by requesting `$YOUR_
 wget $YOUR_DOMAIN/saml/v2/certificate -O idp.crt
 ```

-Always replace `$YOUR_DOMAIN` with your instance domain.
+Always replace `$YOUR_DOMAIN` with your custom domain.

 Use the following configuration

@@ -78,7 +78,7 @@ The request from the API to the introspection endpoint should be in the followin

 ```bash
 curl --request POST \
- --url {your_domain}/oauth/v2/introspect \
+ --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --header 'Authorization: Basic {your_basic_auth_header}' \
 --data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...
@@ -135,7 +135,7 @@ Payload:
 {
   "iss": "78366401571920522@acme", (clientId from your key file)
   "sub": "78366401571920522@acme", (clientId from your key file)
-   "aud": "https://{your_domain}", (your ZITADEL domain/issuer URL)
+   "aud": "https://${CUSTOM_DOMAIN}", (your ZITADEL domain/issuer URL)
   "exp": 1605183582, (Unix timestamp of the expiry)
   "iat": 1605179982   (Unix timestamp of the creation signing time of the JWT, MUST NOT be older than 1h)
 }
@@ -146,7 +146,7 @@ Create the JSON Web Token with the above header and payload, and sign it with th
 The request from the API to the introspection endpoint should be in the following format:
 ```bash
 curl --request POST \
- --url {your_domain}/oauth/v2/introspect \
+ --url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
 --data client_assertion=eyJhbGciOiJSUzI1Ni... \
@@ -161,7 +161,7 @@ def introspect_token(self, token_string):
    payload = {
        "iss": API_PRIVATE_KEY_FILE["client_id"],
        "sub": API_PRIVATE_KEY_FILE["client_id"],
-        "aud": ZITADEL_DOMAIN,
+        "aud": CUSTOM_DOMAIN,
        "exp": int(time.time()) + 60 * 60,  # Expires in 1 hour
        "iat": int(time.time())
    }
@@ -26,7 +26,7 @@ You can find a minimal configuration in the [official documentation](https://git
 The following parameters must be set with the values from ZITADEL.

 ```yaml
-OIDCProviderMetadataURL https://<your_domain>.zitadel.cloud/.well-known/openid-configuration
+OIDCProviderMetadataURL https://${CUSTOM_DOMAIN}/.well-known/openid-configuration
 OIDCClientID <client_id, eg 227791....@apache_test>
 # OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
 OIDCRedirectURI <redirect_uri, eg http://localhost:8080/secure/callback>
@@ -40,7 +40,7 @@ With the following parameters

 | Parameter | Description | Example value|
 |---|---|---|
-| OIDCProviderMetadataURL | Is the url to the discovery endpoint, which is typically located at `{your-domain}/.well-known/openid-configuration`| `https://<your_domain>.zitadel.cloud/.well-known/openid-configuration` |
+| OIDCProviderMetadataURL | Is the url to the discovery endpoint | `https://${CUSTOM_DOMAIN}/.well-known/openid-configuration` |
 | OIDCClientID | Is the ID of the zitadel application. You can find it on the settings page of the application.  | 123456789123@apache_test |
 | OIDCRedirectURI | Users will be redirected to this page after successful login. If you are using localhost or any other non-https endpoint, make sure to enable development mode in ZITADEL. | https://mysecureapp.io/secure/callback |
 | OIDCCryptoPassphrase | Create a secure passphrase. Consult the module's documentation for more details. | ... |
@@ -149,7 +149,7 @@ The Login Policy defines how the login process should look like and which authen
 The Default Redirect URI will be used, if a user calls the login page directly.
 More specifically, typically a client will initiate login with an auth request.
 The auth request contains a client-id and a redirect uri, that must match the configuration in ZITADEL.
-If there is no [auth request](https://zitadel.com/playgrounds/oidc), users will be redirected to the Default Redirect URI, which is by default `https://<custom_domain>/ui/console/`
+If there is no [auth request](https://zitadel.com/playgrounds/oidc), users will be redirected to the Default Redirect URI, which is by default `https://${CUSTOM_DOMAIN}/ui/console/`

 Reasons why ZITADEL doesn't have a redirect URI:

@@ -158,7 +158,7 @@ Reasons why ZITADEL doesn't have a redirect URI:

 We recommend setting your own default redirect URI, if you do not want end users to access ZITADEL console.

-Change default redirect url of instance: `https://<custom_domain>/ui/console/settings?id=login`
+Change default redirect url of instance: `https://${CUSTOM_DOMAIN}/ui/console/settings?id=login`

 <img
  src="/docs//img/guides/solution-scenarios/console-default-redirect.png"
@@ -268,9 +268,9 @@ If this is enabled all created domains on an organization must be verified per d
 More about how to verify a domain [here](/guides/manage/console/organizations#domain-verification-and-primary-domain).
 If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login.

-### SMTP Sender Address matches Instance Domain
+### SMTP Sender Address matches Custom Domain

-If enabled, the SMTP server address must match the instance's primary domain.
+If enabled, the SMTP server address must match the instance's primary custom domain.
 With that you can ensure that users receive notifications from the same domain that is used for login.

 ### Use email as username
@@ -42,7 +42,7 @@ At the moment the username only allows e-mail formatted input. (This will be cha
 If this behavior is not suitable for you, ZITADEL has the option to suffix the usernames with the organization domain.
 This setting is called **User Loginname must contain orgdomain** and is part of your [Domain settings](./default-settings#domain-settings).

-Those loginnames consist of the format `{username}@{domainname}.{zitadeldomain}`.
+Those loginnames consist of the format `{username}@{domainname}.${CUSTOM_DOMAIN}`.
 If your user had the username `john.doe`, the generated loginname would be `john.doe@acme.zitadel.cloud`.
 This also means that only one user with the username `john.doe` can exist in your organization called `ACME`.

@@ -135,7 +135,7 @@ Read more about the [scopes](/docs/apis/openidoauth/scopes#reserved-scopes) or t

 ## Default organization

-On the Default settings page ($YOUR_DOMAIN//ui/console/orgs) you can set an organization as default organization.
+On the Default settings page (`${CUSTOM_DOMAIN}`/ui/console/orgs) you can set an organization as default organization.
 Click the "..." on the right hand side of the table and select "Set as default organization".

 The current default organization is marked by a label "Default".
@@ -5,7 +5,7 @@ sidebar_label: Overview

 ## What is console?

-Console is the Dashboard UI for your instance. It can be accessed from all configured instance domains, defined in the Customer Portal.
+Console is the Dashboard UI for your instance. It can be accessed from all configured custom domains, defined in the Customer Portal.
 The console is used to configure global default settings and can be used by multiple Managers.
 Read more about [Console Managers](./managers) here.

@@ -18,7 +18,7 @@ You would have to create roles for administration and your clients in this very

 ## Create a project

-To create a project, navigate to your organization, then projects or directly via `https://{your_domain}.zitadel.cloud/ui/console/projects`, and then click the button to create a new project.
+To create a project, navigate to your organization, then projects or directly via `https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/projects`, and then click the button to create a new project.

 <img
  alt="Empty Project"
@@ -58,7 +58,7 @@ In our sample scenario, we assume to have the following users:
 - **Michael:** a trainee of Pentagon only using the portal to access his workspace apps. Michael uses his Google Account in combination with his laptops fingerprint.
 - **Bill:** is employed at Octagon as Administrator of the Portal Application. Bill also uses a Microsoft Account in combination with a Security Key to secure his account.

-After having determined the constellation of the organizations and its users, all the necessary data (Portal project with roles and app, users, login requirements, identity providers, branding) should be set up in [Console](https://{your_domain}.zitadel.cloud/ui/console/org).
+After having determined the constellation of the organizations and its users, all the necessary data (Portal project with roles and app, users, login requirements, identity providers, branding) should be set up in [Console](https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/org).
 A B2B [sample application](https://github.com/zitadel/zitadel-nextjs-b2b). for NextJS can be found [here](../../examples/login/nextjs-b2b).

 To allow another organization to use a project, a project grant has to be created. Upon creation, roles for a grant can be limited to a subset of the total project roles.
@@ -14,7 +14,7 @@ When planning your applications, investing time in researching your apps archite
 This guide introduces you to the grouping and structuring of ZITADEL projects which forms the base for all projects. This can be used as a quick start to the [B2B scenario](./b2b), which is merely focused on planning considerations if you are having projects with multiple organizations.

 The journey of this guide starts with creating an Organization, the outermost layer of ZITADEL within your instance, as it is the vessel for projects, roles, applications and users.
-Creation can be done from [ZITADEL Console](https://{your_domain}.zitadel.cloud/ui/console/orgs/create). You can choose your current account for the organization owner or create a new one.
+Creation can be done from [ZITADEL Console](https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/orgs/create). You can choose your current account for the organization owner or create a new one.

 Depending on your Software Development Life Cycle (SDLC) you can create multiple organizations or projects to keep your applications environments seperated.

@@ -40,7 +40,7 @@ Requests to the management API are rate limited. Read our [Rate limit Policy](/d

 User Authentication can be performed in multiple ways. Default method in ZITADEL is username and password with MFA enabled.
 ZITADEL allows you to configure Multifactor- and Passwordless Authentication in order to enhance security for your users. All authentication methods are available from the FREE Tier.
-To setup your organizations login policy, go to your organizations detail in [Console](https://{your_domain}.zitadel.cloud/ui/console/org).
+To setup your organizations login policy, go to your organizations detail in [Console](https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/org).

 When planning your application consider the following questions about User Authentication:

@@ -57,7 +57,7 @@ More detailed information about creating a PAT and manager roles you can find [h

 Then you have to send the following request:
 ```bash
-curl -L -X PUT "https://$CUSTOM_DOMAIN/management/v1/projects/$PROJECT_ID" \
+curl -L -X PUT "https://${CUSTOM_DOMAIN}/management/v1/projects/$PROJECT_ID" \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H "Authorization: Bearer $PAT" \
@@ -161,7 +161,7 @@ Caches:
 All HTTP and gRPC requests sent to ZITADEL receive an instance context. The instance is usually resolved by the domain from the request. In some cases, like the [system service](/docs/apis/resources/system/system-service), the instance can be resolved by its ID. An instance object contains many of the [default settings](/docs/guides/manage/console/default-settings):

 - Instance [features](/docs/guides/manage/console/default-settings#features)
- Instance domains: generated and [custom](/docs/guides/manage/cloud/instances#add-custom-domain)
+- Custom domains: generated and [custom](/docs/guides/manage/cloud/instances#add-custom-domain)
 - [Trusted domains](/docs/apis/resources/admin/admin-service-add-instance-trusted-domain)
 - Security settings ([IFrame policy](/docs/guides/solution-scenarios/configurations#embedding-zitadel-in-an-iframe))
 - Limits[^2]
@@ -209,7 +209,7 @@ export function SetAuthRequest() {
      </div>
      <div className="flex flex-col">
        <label className={`${labelClasses} text-yellow-500`}>
-          Instance Domain
+          Custom Domain
        </label>
        <input
          className={inputClasses(false)}
@@ -39,7 +39,7 @@ export function SetEnvironment() {
  return (
    <div>
      <div className={styles.inputwrapper}>
-        <label className={styles.label}>Your instance domain</label>
+        <label className={styles.label}>Your custom domain</label>
        <input
          className={styles.input}
          id="instance"