Assign application roles to users

B2B applications often require different levels of access for different users. Roles are a powerful way to manage these permissions and ensure that users can only access the features and data appropriate for them.

For example, you might have roles like:

Admin: Can access all features, including billing and user management.
Editor: Can create and edit content, but cannot manage users or settings.
Viewer: Can only view content, but cannot make any changes.

Scalekit provides a flexible role-based access control (RBAC) system that allows you to define custom roles and assign them to users, helping you build a secure and scalable application.

How roles work

By default, Scalekit provides two roles: admin and member. When the first user signs up and creates an organization, they are automatically assigned the admin role. Any subsequent users who join the organization are assigned the member role by default.

Managing roles

You can manage roles, including creating custom ones, from the Scalekit dashboard:

Navigate to User Management > Roles.
You will see a list of existing roles. Click + Add Roles to create a new role.
For each new role, you can define a Display Name, Name, and Description. The Name is what you will receive in the token and use in your application to control access.

Integrate with Scalekit Follow our quickstart guide to integrate Scalekit into your application and start managing user roles.

You can change the default role for both the organization creator and new members at any time in the User Management → Roles section of the dashboard.

Accessing user roles

Once a user is authenticated, their assigned roles are included in the idToken and accessToken. You can use this information in your application’s backend to control access to different resources.

The roles claim in the tokens contains the role key as name (not the display name). For example, if you create a role with the key "editor" and display name "Content Editor", the token will contain "editor" in the roles array.

While the roles claim is an array, Scalekit currently supports a single role per user within an organization.

Here’s an example of a decoded idToken containing the roles claim:

ID Token (decoded)
Access Token (decoded)

1
{
2
  "amr": [
3
    "conn_123456789012345678"
4
  ],
5
  "at_hash": "QwertyUioP",
6
  "aud": [
7
    "skc_987654321098765432"
8
  ],
9
  "azp": "skc_987654321098765432",
10
  "c_hash": "A1b2C3d4E5",
11
  "client_id": "skc_987654321098765432",
12
  "email": "john.doe@example.com",
13
  "email_verified": true,
14
  "exp": 1753441845,
15
  "family_name": "Doe",
16
  "given_name": "John",
17
  "iat": 1750849845,
18
  "iss": "http://example.localhost:8889",
19
  "name": "John Doe",
20
  "oid": "org_987654321098765432",
21
  "roles": [
22
    "member"
23
  ],
24
  "sid": "ses_987654321098765432",
25
  "sub": "usr_987654321098765432"
26
}

1
{
2
  "aud": [
3
    "skc_987654321098765432"
4
  ],
5
  "client_id": "skc_987654321098765432",
6
  "exp": 1750850145,
7
  "iat": 1750849845,
8
  "iss": "http://example.localhost:8889",
9
  "jti": "tkn_987654321098765432",
10
  "nbf": 1750849845,
11
  "roles": [
12
    "member"
13
  ],
14
  "sid": "ses_987654321098765432",
15
  "sub": "usr_987654321098765432",
16
  "xuid": "john.doe"
17
}

With the role information readily available in the tokens, you can implement fine-grained access control in your application logic.