Let organizations manage their own roles

Organization-managed roles and permissions are available on the Kinde Scale plan.

By default, roles and permissions are defined once for your whole business and shared by every organization. On the Scale plan, you can also let each organization define roles and permissions of its own. This is useful when your customers need role structures you cannot predict, for example a customer who wants a billing-approver role that only exists in their organization.

This topic explains how organization-managed roles work, how to control which permissions organizations can use, and how to manage organization roles in Kinde, in the self-serve portal, and through the Kinde Management API.

How organization-managed roles work

Link to this section

• Business-wide roles still apply. Roles you define under Settings > User management > Roles are available in every organization. Organization roles are added on top of them.
• Organization roles belong to one organization. An organization can assign a role it creates only to its own members. Other organizations never see it.
• They are not isolated per environment. Like business-wide roles, organization roles and permissions are defined at the business level. A role an organization creates in development is the same role for that organization in staging and production. See Are Kinde roles and permissions shared across environments?.
• Organization roles hold two kinds of permissions. The organization’s own permissions, and the business-wide permissions you have marked as Available to organization roles. An organization cannot add any other business-wide permission to its roles.
• Organization permissions only reach users through organization roles. You cannot grant an organization permission directly to a user. Add it to one of the organization’s roles and assign the role instead.
• They work in tokens like any other role or permission. Their permissions appear in the permissions claim alongside business-wide permissions, and the roles themselves appear in the roles claim once you add roles to the access token for the application. Your application code does not need to distinguish them.
• Keys must be unique. An organization role or permission key must be unique within that organization, and it cannot match a business-wide key. Likewise, you cannot create a business-wide role or permission with a key that an organization is already using. Keys cannot be changed after creation.
• Limits apply. Each organization can have up to 100 roles and 100 permissions of its own. Names and keys can be up to 64 characters, and descriptions up to 255 characters.
• Organization roles do not affect MFA exemptions. Only business-wide roles can be used as MFA exempt roles for an organization.

Choose which business permissions organizations can use

Link to this section

Before an organization can build roles from your business-wide permissions, you need to mark those permissions as available to organization roles. Permissions that are not marked stay reserved for business-wide roles.

1. In Kinde, go to Settings > User management > Permissions.

2. Select Add permission, or select the three dots next to an existing permission and choose Edit permission.

   

3. Switch on Available to organization roles.

   

4. Select Save.

If you switch Available to organization roles off for a permission, it is removed from every organization role that includes it, in every environment. Members who have those roles lose the permission the next time a new access token is issued for them, unless a business-wide role they hold, or a direct grant, still grants it. Tokens already issued keep the permission until they expire, because a refresh returns the existing access token while it is unexpired.

Add an organization permission in Kinde

Link to this section

An organization permission can only be used in that organization’s roles.

1. In Kinde, go to Organizations and select the organization you want to modify.

2. In the side menu, select Roles.

   

3. Select Add permission.

4. Give the permission a Name, for example ‘Approve invoices’.

5. Enter a Key, for example approve:invoices. The key must be unique within the organization and cannot be changed later.

6. Enter a Description.

   

7. Select Save. The permission can now be added to the organization’s roles.

Add an organization role in Kinde

Link to this section

1. In Kinde, go to Organizations and select the organization.

2. In the side menu, select Roles. The page lists the roles and permissions that belong only to this organization.

   

3. Select Add role.

4. Give the role a Name. Keep it short and descriptive, for example ‘Billing approver’.

5. Enter a Key. This is how the role appears in tokens, for example billing-approver. The key must be unique within the organization and cannot be changed later.

6. Enter a Description of what the role is for and who should have it.

7. Switch on the Permissions to include in the role. The list shows the business-wide permissions you have made available to organization roles, and this organization’s own permissions.

   

8. Select Save.

If no permissions are listed, the organization has no permissions of its own yet, and no business-wide permissions have been made available to organization roles. Add an organization permission, or mark a business-wide permission as available, before you create the role.

Edit or delete organization roles and permissions

Link to this section

Like business-wide roles, changes apply to a member the next time a new access token is issued for them, for example when they sign in again or their current token expires. A refresh returns the existing access token while it is unexpired, so tokens already issued keep their claims until they expire. To apply a change to a member sooner, call the Refresh User Claims endpoint for that user. See Force-update of token claims.

1. In Kinde, go to Organizations and select the organization.

2. In the side menu, select Roles.

3. Select the three dots next to the role or permission and choose Edit or Delete.

   

4. Make your changes and select Save, or confirm the deletion.

   Deleting roles and permissions is permanent

   Deleting an organization role removes it from every member who has it, and from the organization’s default roles. Deleting an organization permission removes it from every organization role that includes it. Neither deletion can be reversed.

Assign organization roles to members

Link to this section

Organization roles are assigned the same way as business-wide roles. See Apply roles and permissions to users.

• In Kinde, open the user, select Roles, choose the organization, and switch on the role. The organization’s own roles are listed alongside your business-wide roles for that organization.
• In the self-serve portal, authorized members can assign organization roles when they invite a member or edit a member’s roles.
• On the Scale plan with advanced organization features, you can also make an organization role a default role for the organization, so new members receive it automatically.

Let organization admins manage roles in the self-serve portal

Link to this section

You can let an organization’s admins create and manage roles and permissions for that organization without contacting you.

1. In Kinde, go to Settings > Environment > Self-serve portal. To enable this for a single organization instead, see Customize the self-serve portal for an organization.

2. In the Organization self-management section, switch on Roles. The switch is off by default.

   

3. If it is not already on, also switch on Members, so admins can assign the roles they create. To let them assign roles while inviting members, invitations must also be allowed for the environment. See Invite members from the portal.

4. Select Save.

Access inside the portal is controlled by two system permissions:

• org:read:roles lets a member view the organization’s roles and permissions.
• org:write:roles lets a member create, edit, and delete them.

The Kinde-managed owner role includes both. To give other members access, add these permissions to the roles you assign to them. See Portal access control with system permissions.

In the portal, members with access open Roles to add roles and permissions, and open Members to assign roles. Assigning roles from Members needs the org:write:members permission.

Manage organization roles via the Kinde Management API

Link to this section

Organization roles and permissions have their own endpoints under the organization. Business-wide endpoints such as List roles and List permissions return business-wide roles and permissions only.

Action	Endpoint	Scope
List organization roles	GET /api/v1/organizations/{org_code}/roles	read:organization_roles
Add organization role	POST /api/v1/organizations/{org_code}/roles	create:organization_roles
Get organization role	GET /api/v1/organizations/{org_code}/roles/{role_id}	read:organization_roles
Update organization role	PATCH /api/v1/organizations/{org_code}/roles/{role_id}	update:organization_roles
Delete organization role	DELETE /api/v1/organizations/{org_code}/roles/{role_id}	delete:organization_roles
List organization permissions	GET /api/v1/organizations/{org_code}/permissions	read:organization_roles
Add organization permission	POST /api/v1/organizations/{org_code}/permissions	create:organization_roles
Get organization permission	GET /api/v1/organizations/{org_code}/permissions/{permission_id}	read:organization_roles
Update organization permission	PATCH /api/v1/organizations/{org_code}/permissions/{permission_id}	update:organization_roles
Delete organization permission	DELETE /api/v1/organizations/{org_code}/permissions/{permission_id}	delete:organization_roles

See the Organizations section of the Management API reference for request and response details.

Things to know when using the API:

• To make a business-wide permission available to organization roles, set is_organization_role_assignable to true when you add or update the permission. The field is also returned when you list permissions.
• When you add a role, permissions is an array of permission IDs. The request fails with PERMISSION_NOT_ASSIGNABLE if any of them is not available to the organization’s roles. When you update a role, permissions replaces the role’s entire permission set.
• Role and permission keys cannot be changed after creation. A PATCH that sends a different key fails with KEY_IMMUTABLE.
• When you add users to an organization or update their roles, a role key can be a business-wide role or one of that organization’s own roles. A key that is neither fails with INVALID_ROLES.
• Adding a role or permission for an organization fails with PLAN_LIMIT_REACHED if your business is not on the Scale plan. Listing and deleting still work, so you can clean up after a downgrade.

Webhooks

Link to this section

Organization roles and permissions use the same role.created, role.updated, role.deleted, permission.created, permission.updated, and permission.deleted webhook events as business-wide roles and permissions. When the role or permission belongs to an organization, data.role or data.permission includes an organization_code field. Business-wide permission events include is_organization_role_assignable instead.

Here is a decoded role.created event for an organization role. See About webhooks for the full payload format.

{
  "data": {
    "role": {
      "id": "018f3d4e-6f2a-7a1b-9c3d-2e4f5a6b7c8d",
      "name": "Billing approver",
      "key": "billing-approver",
      "description": "Can approve invoices for this organization",
      "organization_code": "org_7d8e9f0a1b2c"
    }
  },
  "event_id": "event_1234567890",
  "event_timestamp": "2026-10-27T12:00:00.000Z",
  "source": "admin",
  "timestamp": "2026-10-27T12:00:00.000Z",
  "type": "role.created"
}

What happens if you move off the Scale plan

Link to this section

If your business moves to a plan without organization-managed roles:

• Existing organization roles and permissions are kept, but they are no longer included in new tokens or permission checks. Tokens issued before the downgrade keep their claims until they expire. Members keep their assignments in Kinde, and those roles and permissions are included again if you upgrade.
• You cannot add or edit organization roles and permissions in Kinde, in the portal, or through the API. You can still delete them.
• The Roles page is hidden in the self-serve portal.
• In Kinde, the organization’s Roles tab shows an upgrade banner.