Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Assign roles to users

Learn how to assign roles to users in your application using the dashboard, SDK, or automated provisioning

After registering roles and permissions for your application, Scalekit provides multiple ways to assign roles to users. These roles allow your app to make the access control decisions as scalekit sends them to your app in the access token.

Auto assign roles as users join organizations

Section titled “Auto assign roles as users join organizations”

By default, the organization creator automatically receives the admin role, while users who join later receive the member role. You can customize these defaults to match your application’s security requirements. For instance, in a CRM system, you may want to set the default role for new members to a read-only role like viewer to prevent accidental data modifications.

  1. Go to Dashboard > Roles & Permissions > Roles tab
  2. Select the roles available and choose defaults for organization creator and member

This automatically assigns these roles to every users who joins any organization in your Scalekit environment.

Let users assign roles to others API

Section titled “Let users assign roles to others ”

Enable organization administrators to manage user roles directly within your application. By building features like “Change role” or “Assign permissions” into your app, you can provide a management experience without requiring administrators to leave your app.

To implement role assignment functionality, follow these essential prerequisites:

  1. Verify administrator permissions: Ensure the user performing the role assignment has the admin role or an equivalent role with the necessary permissions. Check the permissions property in their access token to confirm they have role management capabilities.

    Verify permissions
    // Decode JWT and check admin permissions
    const decodedToken = decodeJWT(adminAccessToken);
    

    // Check if user has admin role or required permissions
    const isAdmin = decodedToken.roles.includes('admin');
    const hasPermission = decodedToken.permissions?.includes('users.write') ||
                        decodedToken.permissions?.includes('roles.assign');
    

    if (!isAdmin && !hasPermission) {
      throw new Error('Insufficient permissions to assign roles');
    }

  2. Collect required identifiers: Gather the necessary parameters for the API call:

    • user_id: The unique identifier of the user whose role you’re changing
    • organization_id: The organization where the role assignment applies
    • roles: An array of role names to assign to the user
    Collect and validate identifiers
    // Structure and validate role assignment data
    const roleAssignmentData = {
      user_id: targetUserId,
      organization_id: targetOrgId,
      roles: newRoles,
      // Additional metadata for auditing
      performed_by: decodedToken.sub,
      timestamp: new Date().toISOString()
    };
    

    // Validate required fields
    if (!roleAssignmentData.user_id || !roleAssignmentData.organization_id || !roleAssignmentData.roles) {
      throw new Error('Missing required identifiers for role assignment');
    }

  3. Call Scalekit SDK to update user role: Use the validated data to make the API call that assigns the new roles to the user through the Scalekit membership update endpoint.

    Update user role with Scalekit SDK
    // Use case: Update user membership after validation
    const validationResult = await prepareRoleAssignment(
      adminAccessToken,
      targetUserId,
      targetOrgId,
      newRoles
    );
    

    if (!validationResult.success) {
      return res.status(403).json({ error: validationResult.error });
    }
    

    // Initialize Scalekit client (reference installation guide for setup)
    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET
    );
    

    // Make the API call to update user roles
    try {
      const result = await scalekit.membership.updateMembership({
        user_id: validationResult.data.user_id,
        organization_id: validationResult.data.organization_id,
        roles: validationResult.data.roles
      });
    

      console.log(`Role assigned successfully:`, result);
      return res.json({
        success: true,
        message: "Role updated successfully",
        data: result
      });
    } catch (error) {
      console.error(`Failed to assign role: ${error.message}`);
      return res.status(500).json({
        error: "Failed to update role",
        details: error.message
      });
    }

  4. Handle response and provide feedback: Return appropriate success/error responses to the administrator and update your application’s UI accordingly.

    Handle API response
    // Success response handling
    if (result.success) {
      // Update UI to reflect role change
      await updateUserInterface(targetUserId, newRoles);
    

      // Send notification to user (optional)
      await notifyUserOfRoleChange(targetUserId, newRoles);
    

      // Log the action for audit purposes
      await logRoleChange({
        performed_by: decodedToken.sub,
        target_user: targetUserId,
        organization: targetOrgId,
        old_roles: previousRoles,
        new_roles: newRoles,
        timestamp: new Date().toISOString()
      });
    }

Automate role assignment with directory groups (SCIM)

Section titled “Automate role assignment with directory groups (SCIM)”

Use SCIM provisioning to map directory provider groups to your app roles. When administrators add users to groups in their directory, Scalekit sends events so your app can update roles automatically. This reduces manual changes and keeps access aligned with enterprise policies.

See the full guide at Group-based role assignment.