> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Roles

Define and assign organization roles
<div class="sdk-client-page">

Use the `role` client to define organization roles and list role assignments.

Create roles and permissions for authorization after you have organizations and users.

### createRole
<div class="sdk-method-section">
  
    
      

      Creates a new environment-level role with specified permissions.

      
        Role creation object containing:
      
      
        The created role with metadata
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.createRole({
  name: 'content_editor',
  displayName: 'Content Editor',
  description: 'Can create and edit content',
  permissions: ['content:read', 'content:write', 'content:edit']
});
```

    
  
</div>

### getRole
<div class="sdk-method-section">
  
    
      

      Retrieves complete information for a specific environment role.

      
        Unique role identifier (alphanumeric with underscores, hyphens allowed).
      
      
        Role details including permissions and inheritance
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.getRole('content_editor');
console.log('Role:', response.role.displayName);
console.log('Permissions:', response.role.permissions);
```

    
  
</div>

### listRoles
<div class="sdk-method-section">
  
    
      

      Lists all environment-level roles available in your Scalekit environment.

      
        Array of all roles with their metadata
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.listRoles();
response.roles.forEach(role => {
  console.log(`${role.displayName}: ${role.permissions.length} permissions`);
});
```

    
  
</div>

### updateRole
<div class="sdk-method-section">
  
    
      

      Updates an existing environment role's properties and permissions.

      
        Role to update
      
      
        Updated role properties
      
      
        Updated role details
      

```typescript wrap showLineNumbers=false
await scalekit.role.updateRole('content_editor', {
  displayName: 'Content Editor (Updated)',
  permissions: ['content:read', 'content:write', 'content:edit', 'content:review']
});
```

    
  
</div>

### deleteRole
<div class="sdk-method-section">
  
    
      

      Deletes an environment role and reassigns its users to another role.

      
        Role to delete
      
      
        Optional. Target role for user migration
      
      
        Empty response on success
      

```typescript wrap showLineNumbers=false
await scalekit.role.deleteRole('old_role', 'new_role');
```

    
  
</div>

### deleteRoleBase
<div class="sdk-method-section">
  
    
      

      Removes an environment role's inheritance relationship, eliminating inherited permissions from its base role.

      
        Role to remove inheritance from
      
      
        Empty response on success
      

    
  
</div>

### getRoleUsersCount
<div class="sdk-method-section">
  
    
      

      Gets the number of users assigned to an environment role.

      
        Role to count users for
      
      
        Total user count (direct and inherited)
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.getRoleUsersCount('admin');
console.log(`${response.count} users have admin role`);
```

    
  
</div>

### createOrganizationRole
<div class="sdk-method-section">
  
    
      

      Creates a new organization-specific role with custom permissions.

      
        Organization identifier (format: "org_...")
      
      
        Role configuration containing:
      
      
        Created organization role
      

```typescript wrap showLineNumbers=false
await scalekit.role.createOrganizationRole('org_123456', {
  name: 'department_lead',
  displayName: 'Department Lead',
  description: 'Manages department members',
  permissions: ['dept:members:read', 'dept:members:invite']
});
```

    
  
</div>

### getOrganizationRole
<div class="sdk-method-section">
  
    
      

      Retrieves details for a specific organization role.

      
        Organization identifier
      
      
        Role name to retrieve
      
      
        Organization role details
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.getOrganizationRole(
  'org_123456',
  'department_lead'
);

console.log('Permissions:', response.role.permissions);
```

    
  
</div>

### listOrganizationRoles
<div class="sdk-method-section">
  
    
      

      Lists all roles available to an organization (environment + organization-specific).

      
        Organization identifier
      
      
        Array of available roles
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.listOrganizationRoles('org_123456');
response.roles.forEach(role => {
  console.log(`${role.displayName} (${role.scope})`);
});
```

    
  
</div>

### updateOrganizationRole
<div class="sdk-method-section">
  
    
      

      Updates an organization role's properties and permissions.

      
        Organization identifier
      
      
        Role to update
      
      
        Updated role properties
      
      
        Updated role
      

```typescript wrap showLineNumbers=false
await scalekit.role.updateOrganizationRole('org_123456', 'department_lead', {
  permissions: ['dept:members:read', 'dept:members:invite', 'dept:members:remove']
});
```

    
  
</div>

### deleteOrganizationRole
<div class="sdk-method-section">
  
    
      

      Deletes an organization role and reassigns its users.

      
        Organization identifier
      
      
        Role to delete
      
      
        Optional. Target role for user migration
      
      
        Empty response on success
      

```typescript wrap showLineNumbers=false
await scalekit.role.deleteOrganizationRole(
  'org_123456',
  'old_role',
  'new_role'
);
```

    
  
</div>

### getOrganizationRoleUsersCount
<div class="sdk-method-section">
  
    
      

      Gets the number of users assigned to an organization role.

      
        Organization identifier
      
      
        Role to count users for
      
      
        User count
      

```typescript wrap showLineNumbers=false
const response = await scalekit.role.getOrganizationRoleUsersCount(
  'org_123456',
  'admin'
);

console.log(`${response.count} admins in this organization`);
```

    
  
</div>

### updateDefaultRoles
<div class="sdk-method-section">
  
    
      

      Sets the default creator and/or member roles for the environment.

      
        Optional fields: `defaultCreatorRole`, `defaultMemberRole`.
      
      
        Updated default roles configuration
      

    
  
</div>

### listDependentRoles
<div class="sdk-method-section">
  
    
      

      Lists all roles that extend (depend on) the specified role.

      
        Role to find dependents for
      
      
        Array of roles that depend on the given role
      

    
  
</div>

### updateDefaultOrganizationRoles
<div class="sdk-method-section">
  
    
      

      Sets the default role automatically assigned to new organization members.

      
        Organization identifier
      
      
        Role name to assign by default
      
      
        Updated configuration
      

```typescript wrap showLineNumbers=false
await scalekit.role.updateDefaultOrganizationRoles('org_123456', 'member');
```

    
  
</div>

### deleteOrganizationRoleBase
<div class="sdk-method-section">
  
    
      

      Removes a role's inheritance relationship, eliminating inherited permissions from base role.

      
        Organization identifier
      
      
        Role to remove inheritance from
      
      
        Empty response on success
      

```typescript wrap showLineNumbers=false
await scalekit.role.deleteOrganizationRoleBase('org_123456', 'custom_role');
```

    
  
</div>

</div>


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |