How to automatically assign a standard role to new users created via the API

[tunecrew]

So I'm creating new users via the API using a service user token and the v2/users/human endpoint. This works fine.

What I can't figure out is how to then add a role to the newly created user without doing it manually in the dashboard.

I'd like to be able to do this either by:

• An action that fires on post-creation - can't figure out how to make this work where the JS code is just hosted in the Actions section of the dashboard.

I created this script in the Actions section:

function addDefaultRole(ctx, api)
{
	api.userGrants.push(
		{	
			projectID: '<MY_PROJECT_ID>', roles: ['<MY_ROLE_KEY>']
		}
	);
}

and created a Flow with External Authentication -> Post Creation

It does not run when I create a new user though.

• Just call an API endpoint, but this only seems possible w/ V1, which I assume will be deprecated. Also a bit confusing - how does Add Project Member differ from Add Project Grant Member from Add User Grant?

[tunecrew]

I'll add that I can't get the V1 API to work - if I call management/v1/projects/:projectId/members I get a 403 unless I give my service user the Org Owner role, and then I get a 400.

[uldyssian-sh]

In ZITADEL, the “Actions / Flows” you configured (External Authentication → Post creation) are tied to interactive authentication/registration flows.

If you create users directly via the API endpoint POST /v2/users/human, that is a management-style user creation call and it will not necessarily trigger the same “Post creation” flow you expect from the login/registration pipeline.

So for users created via the API, the supported/reliable solution is:

Create the user

Then explicitly add a user grant (project role) via the Management API.

You want a “user grant” (application role membership), not a “project member” or “project grant member”:

Project Member / Project Grant Member = administrators who can manage ZITADEL (management roles)

User Grant = the user’s application roles for a project (what you want for default access)

Example flow:

1. Create the user (v2 endpoint is deprecated in docs but still commonly used)

curl -X POST "https://<YOUR_DOMAIN>/v2/users/human"
-H "Authorization: Bearer <SERVICE_USER_TOKEN>"
-H "Content-Type: application/json"
-d '{
"username": "new.user",
"profile": { "givenName": "New", "familyName": "User" },
"email": { "email": "new.user@example.com", "isVerified": true }
}'

This returns the new user’s id.

2. Add the default role via “Add User Grant” (Management API)

curl -X POST "https://<YOUR_DOMAIN>/management/v1/users/<USER_ID>/grants"
-H "Authorization: Bearer <SERVICE_USER_TOKEN>"
-H "Content-Type: application/json"
-d '{
"projectId": "<MY_PROJECT_ID>",
"roleKeys": ["<MY_ROLE_KEY>"]
}'

This is the API that assigns application roles to a user for a project (“user grant”). It is the direct equivalent of what your v1 Action was doing with api.userGrants.push(...). The endpoint is documented as “Add User Grant”. https://zitadel.com/docs/apis/resources/mgmt/management-service-add-user-grant

If you get 403 with your service user token, that means the service user does not have the required ZITADEL management permissions to create user grants (being able to create users is not the same as being allowed to assign project roles). Ensure the service user is authorized to access ZITADEL APIs and has the necessary management permissions for the organization/project. https://zitadel.com/docs/guides/integrate/zitadel-apis/access-zitadel-apis

Summary

Actions/Flows are for auth/registration events, not guaranteed for API-driven user provisioning.

For API-created users, assign the default application role by calling “Add User Grant” right after creation.

Use “User Grant” for app roles; do not use “Project Member / Project Grant Member” unless you are assigning ZITADEL admin/manager roles.

[uldyssian-sh]

Thanks! If this helps, please consider marking it as “Helpful” or “Accepted” 😊