Skip to main content
Use AI Studio → Permissions → JWT-based permissions to grant permissions from JWT claims. These rules read the decoded JWT payload directly; you do not need to configure field mappings first.

​
Prerequisites

  • Admin access to AGO
  • Working widget JWT authentication
  • Active permissions created under AI Studio → Permissions, with the intended agents linked to them
Custom permissions grant access to configured agents and content. A permission named admin or analytics does not grant administration or reporting roles. Manage those roles separately through user management.

​
From JWT Claims to Permissions

1

Choose the claims to match

For example, your authentication service might issue a signed token with these claims. This is a payload illustration, not a usable token; use the issuer, audience, expiry, and signing configuration required by your workspace.
Use the claim’s exact name as the rule field. Nested claims use dot notation, such as user_metadata.subscription or location.region.
2

Create the rule

  1. Open AI Studio → Permissions → JWT-based permissions.
  2. Click Add JWT Rule and name the rule.
  3. Add a condition with a field, operator, and value. For the token above, use field department, operator Equals, and value IT.
  4. Select the permissions to grant, keep the rule active, and click Save.
Each condition must match for the rule to apply. An active rule with no conditions does not match. All matching rules contribute permissions; their priorities do not make one rule cancel another rule’s grants.
3

Link agents and test

  1. Edit each intended agent under AI Studio → Agents and select its permissions in Access Control.
  2. Authenticate the widget with a valid token issued for a non-admin test user.
  3. Check that the expected agents are available. Repeat with a user whose claims do not match.
The JWT rule grants permissions, not direct agent assignments. Staff accounts can access agents independently of these rules, so they are unsuitable for testing customer restrictions.

​
Example Conditions

The permission names below are examples to create in your workspace. Link the desired agents to each permission before testing. For enterprise users in Europe, put both conditions in the same rule. Their condition representation is:
To grant one permission to either pro or enterprise subscribers, create two matching rules that grant the same permission. Multiple conditions within one rule use AND, not OR. For a non-trial audience, combine an Exists condition on user_metadata.subscription with a Not Equals condition whose value is trial. The existence check avoids treating a missing claim as a known non-trial subscription.

​
JWT Field Mappings Are Separate

Under Channels → Widget & SDK, JWT field mappings extract claim values for additional user information. A mapping from user_metadata.subscription to the label Subscription Tier stores that exact label; it does not normalize it to subscription_tier. JWT-based permission rules still use the original claim path user_metadata.subscription. They do not use the display label or a jwt_claims. prefix. The stored jwt_iss value comes from the token’s iss claim and is empty when that claim is absent.

​
Verify the Result

Use a representative non-admin account with a valid signed token. Check matching and nonmatching values, missing claims, and users who match more than one rule. Confirm both the visible agents and whether the user can start the intended conversation. The portal’s permission selector can help preview a permission, but it does not change your identity or test another user’s JWT. Portal sign-in also has a separate email access check.

​
Troubleshooting

  1. Check that the rule and its granted permissions are active.
  2. Check the original JWT claim name, including case and nested path.
  3. Verify that every condition matches the actual payload.
  4. Check that the intended agents are active and linked to the granted permissions.
JWT rules read the original token payload. A display label such as Subscription Tier does not replace the claim path user_metadata.subscription. Check the payload issued by your authentication service.
Review all matching rules, including email/domain rules and direct permission assignments. Grants accumulate; increasing a rule’s priority does not remove permissions granted elsewhere. Test with a non-admin account.