Slef-hosted; How do you obtain roles for a Service User?

We are running self-hosted version: v2.71.8

I am able to obtain roles for Client Users, using the scope:

openid offline_access profile email urn:zitadel:iam:org:project🆔<project>:aud urn:iam:org:project:roles urn:zitadel:iam:org:projects:roles

openid offline_access profile email urn:zitadel:iam:org:project🆔<project>:aud urn:iam:org:project:roles urn:zitadel:iam:org:projects:roles

openid offline_access profile email urn:zitadel:iam:org:project🆔<project>:aud urn:iam:org:project:roles urn:zitadel:iam:org:projects:roles

openid offline_access profile email urn:zitadel:iam:org:project🆔<project>:aud urn:iam:org:project:roles urn:zitadel:iam:org:projects:roles

Via userinfo:

user {
  email: "barry.scott@example.com",
  email_verified: true,
  family_name: "Scott",
  given_name: "Barry",
  locale: null,
  name: "Barry Scott",
  preferred_username: "barry.scott@example.com",
  sub: "<sub>",
  updated_at: 1748336346,
  "urn:zitadel:iam:org:project:<project>:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
  "urn:zitadel:iam:org:project:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
}

user {
  email: "barry.scott@example.com",
  email_verified: true,
  family_name: "Scott",
  given_name: "Barry",
  locale: null,
  name: "Barry Scott",
  preferred_username: "barry.scott@example.com",
  sub: "<sub>",
  updated_at: 1748336346,
  "urn:zitadel:iam:org:project:<project>:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
  "urn:zitadel:iam:org:project:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
}

user {
  email: "barry.scott@example.com",
  email_verified: true,
  family_name: "Scott",
  given_name: "Barry",
  locale: null,
  name: "Barry Scott",
  preferred_username: "barry.scott@example.com",
  sub: "<sub>",
  updated_at: 1748336346,
  "urn:zitadel:iam:org:project:<project>:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
  "urn:zitadel:iam:org:project:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
}

user {
  email: "barry.scott@example.com",
  email_verified: true,
  family_name: "Scott",
  given_name: "Barry",
  locale: null,
  name: "Barry Scott",
  preferred_username: "barry.scott@example.com",
  sub: "<sub>",
  updated_at: 1748336346,
  "urn:zitadel:iam:org:project:<project>:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
  "urn:zitadel:iam:org:project:roles": {
    "api": {
      "<project>": "<org>.us1.zitadel.cloud",
    },
  },
}

But if I try get the roles of a PAT Service User via userinfo, nothing comes through:

user {
  name: "PAT API User",
  preferred_username: "pat_api_user",
  sub: "<sub>",
  updated_at: 1755769128,
  "urn:zitadel:iam:user:resourceowner:id": "<resource>",
  "urn:zitadel:iam:user:resourceowner:name": "<org name>",
  "urn:zitadel:iam:user:resourceowner:primary_domain": "<org>.us1.zitadel.cloud",
}

user {
  name: "PAT API User",
  preferred_username: "pat_api_user",
  sub: "<sub>",
  updated_at: 1755769128,
  "urn:zitadel:iam:user:resourceowner:id": "<resource>",
  "urn:zitadel:iam:user:resourceowner:name": "<org name>",
  "urn:zitadel:iam:user:resourceowner:primary_domain": "<org>.us1.zitadel.cloud",
}

user {
  name: "PAT API User",
  preferred_username: "pat_api_user",
  sub: "<sub>",
  updated_at: 1755769128,
  "urn:zitadel:iam:user:resourceowner:id": "<resource>",
  "urn:zitadel:iam:user:resourceowner:name": "<org name>",
  "urn:zitadel:iam:user:resourceowner:primary_domain": "<org>.us1.zitadel.cloud",
}

user {
  name: "PAT API User",
  preferred_username: "pat_api_user",
  sub: "<sub>",
  updated_at: 1755769128,
  "urn:zitadel:iam:user:resourceowner:id": "<resource>",
  "urn:zitadel:iam:user:resourceowner:name": "<org name>",
  "urn:zitadel:iam:user:resourceowner:primary_domain": "<org>.us1.zitadel.cloud",
}

A role has definitely been set.

Ask Inkeep•10/21/25, 2:36 PM

Hi @Crimbo, 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•10/21/25, 2:37 PM

Answer

The issue you're experiencing with PAT (Personal Access Token) service users not returning roles in the userinfo endpoint is a known limitation. For service users, you need to use a different authentication method to include audience information in the token (1) .

Personal Access Tokens cannot define the audience scope, which is required for role information to be included in the token . To retrieve roles for service users, you should use the JWT profile authentication method instead of PAT .

For service users to receive role information, you need to:

Use JWT profile authentication instead of PAT
Include the proper audience scope in your token request: urn:zitadel:iam:org:project🆔{projectId}:audurn:zitadel:iam:org:project🆔{projectId}:aud (2)
Include the role scope: urn:zitadel:iam:org:projects:rolesurn:zitadel:iam:org:projects:roles

Alternatively, you can use ZITADEL's Auth API to retrieve roles directly. The Auth API provides endpoints specifically for retrieving user authorizations and grants :

List my authorizations/grants: `https://$%7BCUSTOM-DOMAIN%7D/auth/v1/usergrants/me/_search%60
List my project roles: `https://$%7BCUSTOM_DOMAIN%7D/auth/v1/permissions/me/_search%60

These API endpoints work with proper authentication tokens and can retrieve role information for service users when the correct audience is included in the token .

The limitation exists because PAT tokens don't carry project audience information, which is necessary for ZITADEL to determine which project's roles to include in the response (1) .

Ask Inkeep•10/21/25, 2:37 PM

To learn more, see the sources I considered:

[1] Service user calling ListMyProjectOrgsListMyProjectOrgs returns nothing
[2] Retrieve User Roles in ZITADEL

Ask Inkeep•10/21/25, 2:37 PM

Feel free to tag @Ask Inkeep with additional questions.

AAsk Inkeep To learn more, see the sources I considered: [[1] Service user calling `ListM...

Ask InkeepAPP•10/21/25, 2:38 PM

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