Email requirement when creating users

I am currently evaluating Zitadel and have a question regarding its requirement for email addresses. In my previous product, not all users were required to have an email; many logged in using only a username or a PIN.

Could you clarify how strict the email requirement is within the Zitadel model? Is there a method to make the email address optional?

Furthermore, is it possible to define a custom identifier for the identity, specific to a particular project or application?

Thank you for your assistance.

Ask Inkeep•12/1/25, 5:22 PM

Hi @Alejandro, I'm an AI assistant for ZITADEL. While a team member reviews this question, I'll see if I can find relevant sources for your question.

Ask Inkeep•12/1/25, 5:22 PM

Answer

I wasn't able to find a direct answer about making email optional for human users, here are some relevant sources:

Create a User (1) : The API documentation shows that for human users, the email field is marked as "objectrequired" within the user creation structure, suggesting email is mandatory for human user types.
User Metadata (2) : You can attach custom key-value pairs to users as metadata, which could serve as custom identifiers for your project or application needs.

Regarding custom identifiers: When creating a user, you can set a custom

userId

userId

that is unique within the instance (1) . Additionally, you can specify a custom usernameusername that serves as a unique identifier within the organization . For project-specific identifiers, you can use user metadata to link users to internal identifiers (2) .

Ask Inkeep•12/1/25, 5:22 PM

To learn more, see the sources I considered:

[1] Create a User
[2] User Metadata

Ask Inkeep•12/1/25, 5:22 PM

Feel free to tag @Ask Inkeep with additional questions.

AAsk Inkeep To learn more, see the sources I considered: [[1] Create a User](https://zita...

Ask InkeepAPP•12/1/25, 5:29 PM

Got it. Tagging @Rajat for additional help.

Rajat•12/2/25, 10:48 AM

hey @Alejandro welcome to the server and thanks for your question.

For human users, the username can be set independently of the email address. The username is a unique identifier for the user in the org. If not specified, zitadel sets the username to the email for users of type humanhuman and to the

user_id

user_id

for users of type machinemachine.

Rajat•12/2/25, 10:51 AM

For users who don't have email addresses, you could create them as machine users (service accounts) instead of human users if that makes sense??. Machine users don't require an email address and can authenticate using API/RSA keys or PAT. The username for machine users defaults to the

user_id

user_id

when not specified.
the email requirement for human users is indeed strict,the email field is marked as required in the API specification.

AlejandroOP•12/2/25, 3:33 PM

In my case, users with usernames have a password too, so can I use the machine user with username/password?

AAlejandro In my case, users with usernames have a password too, so can I use the machine u...

Rajat•12/3/25, 1:27 PM

no you cannot do that, but in that case you can pass a dummy/test email if that helps and mark isVerifiedisVerified to true from the api specs, you can still use your username/password for login without wanting to use email to login, but you need it during account creation.

AlejandroOP•12/3/25, 3:25 PM

hey @Rajat I see this should be possible on version 5.x according to your roadmap https://zitadel.com/docs/product/roadmap#v5x, is this right? If yes, when would this be released?

ZITADEL Docs

Timeline and Overview

AAlejandro hey <@1346540274674827395> I see this should be possible on version 5.x accordi...

Rajat•12/4/25, 11:24 AM

hey @Alejandro it still in the planning phase as you can see but it should be out early next year