Custom claims / flat roles - Actions V2 with n8n

Hello hello!
I’m in the process of migrating my whole 2 actions from V1 to V2 - namely auto role assignment and flat roles. I’m doing so with n8n.

I just got auto role assignment to work reliably by setting up a webhook, getting user info, performing some checks on the user and finally using the /zitadel.authorizarion.v2.AuthorizationService/CreateAuthorization API endpoint.
My n8n webhook here is trigger under method: /zitadel.user.v2.UserService/AddHumanUser. Such that when a new user is created, external or internal, the n8n flow is run and the new user is auto assigned the desired role.

Now I need to figure out flat roles or custom claims in a similar way. I’ve defined my webhook and and it triggers on function: preaccessToken. Everything looks good here. I’m also able to extract the roles to create a simple json object. However, how do I insert this back into the access token? I tried using n8ns respond to webhook node, but the flow seems to fail. Any ideas here? I ran through the actions v2 custom claims example on github but got confused lol.

As a side note, for stuff like flat roles, it would be better if it were maintained alongside the new actions. It’s quite a basic requirement

Ask Inkeep•12/4/25, 6:00 PM

Hi @AYEEDITYA, 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/4/25, 6:01 PM

Answer

---

I wasn't able to find a direct answer, here are some relevant sources:

questions-help-bugsActions V2 - Adding claims to token questions-help-bugsActions V2 - Adding claims to token : This confirms that adding custom claims to access or ID tokens using Actions V2 API is not currently possible—Actions V2 only supports modifying API requests and responses.
Using Actions (2) : Documents the PreAccessToken function structure, showing the expected JSON response format with append_claimsappend_claims array for adding custom claims to tokens.

For your flat roles migration, the challenge is that Actions V2 doesn't currently support token customization (like adding custom claims to access tokens) questions-help-bugsActions V2 - Adding claims to token . The PreAccessTokenPreAccessToken function trigger you're using is documented for Actions V1, not V2 (2) .

Your n8n webhook response needs to return JSON in this structure :

{
  "append_claims": [
    {
      "key": "key of claim to be set on the user",
      "value": "value of claim to be set on the user"
    }
  ]
}

{
  "append_claims": [
    {
      "key": "key of claim to be set on the user",
      "value": "value of claim to be set on the user"
    }
  ]
}

However, since Actions V2 doesn't support this functionality yet questions-help-bugsActions V2 - Adding claims to token , you may need to continue using Actions V1 for flat roles/custom claims until V2 adds this capability.

If you'd like help from the team, click the "Ask for help" button to tag someone for review.

**

Ask Inkeep•12/4/25, 6:01 PM

To learn more, see the sources I considered:

questions-help-bugsActions V2 - Adding claims to token
[2] Using Actions

Ask Inkeep•12/4/25, 6:01 PM

Feel free to tag @Ask Inkeep with additional questions.

AAsk Inkeep To learn more, see the sources I considered: [[1] Actions V2 - Adding claims ...

Ask InkeepAPP•12/4/25, 6:04 PM

Got it. Tagging @Rajat for additional help.

Rajat•12/8/25, 11:49 AM

hey @AYEEDITYA this may help Extend Authorization in ZITADEL with Organization Metadata + preAccessToken Action please le me know. Thanks

Extend Authorization in ZITADEL with Organization Metadata + preAcc...

Extend ZITADEL auth by mapping roles to permissions via Organization metadata and a preAccessToken Action that appends a permissions claim.

AYEEDITYAOP•12/8/25, 5:12 PM

ahh okayyy i essentially had it! in N8N, i simply missed the config that sets the respond mode to "use respond to webhook node". I initally had it to respond immediately. this has now inserted "flat roles" into the access token and things are looking up. thanks!

AAsk Inkeep To learn more, see the sources I considered: [[1] Actions V2 - Adding claims ...

Ask InkeepAPP•12/8/25, 7:22 PM

Glad I could be helpful. Feel free to create a new thread with any new questions you may have.