Manage user roles

Roles allow you to group permissions into buckets. A role in Kinde could represent a collection of permissions available to an owner, an administrator, a member or whatever role structure is relevant to your business.

This topic covers how to manage roles in the Kinde platform and via the Kinde Management API.

Important things to know about Kinde roles

Link to this section

• User roles are defined at the business level, but applied to users at an organization level
• On the Scale plan, organizations can also define roles of their own that only apply within that organization
• A user can have multiple roles per organization
• The same user can have different roles in different organizations. They could have the admin and owner role in Org A and a member role in Org B
• We recommend you use permissions for controlling access to features within your application, then use roles to group the permissions.
• Roles (and permissions) cannot be assigned to a user unless they belong to an organization.

Tip: Set default roles when a user signs up to an organization

Add user roles in Kinde

Link to this section

1. In Kinde, go to Settings > User Management > Roles. The User roles page opens showing any user roles already defined.
2. Select Add role. The Add role window opens.
3. Give the role a Name. Keep it short and descriptive, so you can easily understand what it is for. For example, ‘Accounts management’.
4. Enter a Description. Describe what a user with this role can do. For example ‘Allows users to perform all basic accounts functions.’
5. Enter a Key. The key is how your code references the role in Kinde. It should be a word that is easy to reference in code and match in your product. You should also follow a naming convention for all roles to help maintain your code.
6. Select if the role should be assigned to all new users by default when they sign up.
7. Select the permissions that are included in the role by switching them on. See also Define user permissions.
8. Select Save.

Edit user roles

Link to this section

You can update user roles via the Kinde Management API or using the procedure below.

User roles are dynamic and refreshed via the issued token. This means that any changes you make will be applied to all users assigned that role, the next time they sign in.

We don’t recommend editing role keys, once a role is in use. It will break the code link between your product and the defined role.

1. Go to Settings > User Management > Roles. If you already have roles, you’ll see a list of them.
2. Select the three dots next to the role you want to edit and choose Edit.
3. Make the changes you want and select Save.

Delete user roles

Link to this section

You can delete user roles via the Kinde Management API or using the procedure below.

When you delete a user role, you will remove the role as well as all the associated permissions from all users who are assigned that role. This can’t be reversed.

1. Go to Settings > User Management > Roles. Your list of roles is shown.
2. Select the three dots next to the role and choose Delete. A confirmation / warning message appears.
3. Select Delete role. The role is deleted permanently.

Add user roles via API

Link to this section

You can add user roles via the Kinde API.

Use the Add Organization User Role end point to assign a role to a user, and get the role IDs from the Roles endpoint.

Add roles to the access token

Link to this section

When a user authorizes against an organization in Kinde, you can enable their roles to be returned as an array of IDs in the roles claim of the access_token. This is part of an additional claim.

To add roles to tokens

Link to this section

1. Go to Settings > Applications > [Your application] > Tokens.
2. Scroll to the Token Customization section.
3. Select Customize on the Access tokens card.
4. Switch on Roles (array) in the Additional claims section.

Our SDKs commonly ship with a getClaim method to help with this. For example in React you could use something like:

getClaim("roles");
// {name: "roles", value: ["admin", "owner"]}

Other role-related functions in the Kinde Management API

Link to this section

• View a list of roles
• View a list of permissions for a role
• Edit permissions for a role
• Remove permissions from a role

Let organizations create their own roles

Link to this section

On the Kinde Scale plan, each organization can define roles and permissions that belong only to that organization. Organization roles can only be assigned to the organization’s members, and can include the organization’s own permissions plus any business-wide permissions you mark as Available to organization roles. They appear in tokens like any other role.

You manage them from Organizations > [organization] > Roles, organization admins can manage them in the self-serve portal, and developers can use the organization roles endpoints in the Management API. See Let organizations manage their own roles.

The roles listed under Settings > User Management > Roles, and returned by the List roles endpoint, are business-wide roles only.

Are Kinde roles and permissions shared across environments?

Link to this section

Yes. Roles and permissions are defined at the business level, not per environment. A role created in your development environment is the same role in staging and production — there is no per-environment isolation. The same rule applies to organization-managed roles: each belongs to one organization, but that definition exists in every environment in your business. If your team needs to test role changes without affecting production, manage each environment in a separate Kinde business.