How to self-host the Zitadel typescript login UI?

Federico Coppede
Federico Coppede

Sales Engineer

Some of our past blog posts cover the topics of designing a custom login flow with our Typescript-based login system.

In this post, we dive into the key aspects of hosting your own custom login UI using the Zitadel typescript library. We will guide you through the steps to deploy your own fully customized login user interface (UI) to Vercel (or the hosting service you prefer) and seamlessly connect it to your Zitadel Instance.

Deploying the custom login UI:

  1. Create a free Zitadel Cloud Instance, that will be used to run this demo (you can also use a self-hosted Zitadel instance, if you prefer): https://zitadel.com/docs/guides/manage/cloud/start
  2. Create a User: Type Machine (formerly known as service user) and assign the IAM Login Client Administrator role in your instance: https://zitadel.com/docs/guides/manage/console/managers image title
  3. Create a PAT (Personal Access Token) for this Service User and save it, it will be needed later: image title
  4. Fork the login UI typescript repository from here: https://github.com/zitadel/typescript
  5. Deploy the project to your Vercel account (you can also deploy it directly from the repository to your Vercel account using the Vercel deploy button in the readme file): a. https://vercel.com/docs/git/vercel-for-github image title b. Set the environment variables required by the app: image title

ZITADEL_API_URL => URL where the Zitadel instance is hosted, for example: https://< INSTANCE_NAME > . zitadel . cloud |

ZITADEL_SERVICE_USER_TOKEN => PAT created in step 3

EMAIL_VERIFICATION=true (Optional: whether a user must have verified email)

  1. After the deployment is completed, copy the domain (without the https://) provided by Vercel and add it as a trusted domain to your instance:

    a. This step requires you to call the Zitadel Management API with a valid access token, you can use a tool like Postman for this. This is an IAM_OWNER access token (not the token from step 3)

To get an access token, follow this guide: https://zitadel.com/docs/guides/integrate/zitadel-apis/access-zitadel-apis#how-to-access-zitadel-apis

b. Trusted domains endpoint: https://zitadel.com/docs/apis/resources/admin/admin-service-add-instance-trusted-domain image title

  1. Open your Zitadel Console and create a new application in your Zitadel instance. Then, enable the new login UI checkbox and add the Vercel application URL as a Custom Base URL for it: https://zitadel.com/docs/examples/login/react#set-up-application-and-obtain-keys

image title

  1. To test your self-hosted login UI, you can use the Zitadel React quickstart application:

    a. https://github.com/zitadel/zitadel-react

    b. Replace this values with the Vercel deployment URL (authority) and the client ID from the Zitadel application just created

    c. Run the application and login image title

Conclusion

Self-hosting the Zitadel TypeScript login UI lets you fully customize your authentication experience while staying secure and scalable. With just a few steps, you can deliver a seamless, branded login flow powered by Zitadel — including the ability to use a different custom login domain per application, a powerful level of flexibility that most of our competitors don’t offer.

Liked it? Share it!