Custom Claims

Custom claims let you add extra information to the JWT tokens that Permiso issues. If your application needs to know something about a user beyond their name and email (for example their department, subscription tier, or internal role), custom claims are how you get that data into the token.

How claims work

When Permiso issues a token for a user, it includes the user's standard profile information (name, email, groups, etc.). Custom claims are additional key-value pairs you define, which get added to the token alongside that standard data.

Your application can then read those values from the token without needing to make a separate API call to look up user attributes.

Adding a custom claim to a user

1. Go to Settings → Administration → Users and open the user you want to add a claim to
2. Scroll to the Custom Claims section and click Add claim
3. Enter a key (e.g. department, subscription_tier) and a value (e.g. Engineering, pro)
4. Click Save

Adding a custom claim to a group

Claims can also be applied at the group level. When a user belongs to a group with claims, those claims are included in their tokens automatically, so you don't need to set them on each user individually.

1. Go to Settings → Administration → User Groups and open the group
2. Find the Custom Claims section and add claims the same way as for users

This is especially useful for role-based attributes. For example, you could add a role: admin claim to an Admins group, and every member of that group will have that claim in their tokens.

When a user and group have conflicting claims

If a user has a claim with the same key as one of their groups, the user-level claim takes precedence.

Reading claims in your application

Custom claims appear in the ID token and the userinfo endpoint response. The claim key is exactly what you entered; no namespace prefix is added. For example, if you set department: Engineering, your app will see:

{
  "sub": "user-id",
  "name": "Alice",
  "department": "Engineering"
}

How you read this depends on your application's OIDC library. Most libraries give you access to the full token payload after authentication.