> **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 `scalekit_client.roles` to define organization roles and list role assignments.

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

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

      Method to list all roles

      
        List Roles Response
      

```python wrap showLineNumbers=false
response = scalekit_client.roles.list_roles()

for role in response[0].roles:
    print(f"Role: {role.name}")
```

    
  
</div>

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

      Method to get role by name

      
        Role name to get role details
      
      
        Get Role Response
      

```python wrap showLineNumbers=false
response = scalekit_client.roles.get_role('admin')
role = response[0].role
```

    
  
</div>

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

      Method to create a new role

      
        CreateRole object with expected values for role creation
      
      
        Create Role Response
      

```python wrap showLineNumbers=false
from scalekit.v1.roles.roles_pb2 import CreateRole

role = CreateRole()
role.name = "editor"
role.display_name = "Editor"

response = scalekit_client.roles.create_role(role)
```

    
  
</div>

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

      Method to update an existing role by name

      
        Role name to update
      
      
        UpdateRole object with expected values for role update
      
      
        Update Role Response
      

```python wrap showLineNumbers=false
from scalekit.v1.roles.roles_pb2 import UpdateRole

role = UpdateRole()
role.display_name = "Senior Editor"

response = scalekit_client.roles.update_role('editor', role)
```

    
  
</div>

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

      Method to delete role by name

      
        Role name to be deleted
      
      
        Replacement role for users.
      
      
        Empty on success.
      

```python wrap showLineNumbers=false
scalekit_client.roles.delete_role('editor', reassign_role_name='viewer')
```

    
  
</div>

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

      Method to get the count of users associated with a role

      
        Role name to get user count for
      
      
        Get Role Users Count Response
      

```python wrap showLineNumbers=false
response = scalekit_client.roles.get_role_users_count('admin')
print(f"User count: {response[0].count}")
```

    
  
</div>

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

      Method to list all organization roles

      
        Organization ID
      
      
        List Organization Roles Response
      

```python wrap showLineNumbers=false
response = scalekit_client.roles.list_organization_roles('org_123456')

for role in response[0].roles:
    print(f"Role: {role.name}")
```

    
  
</div>

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

      Method to create a new organization role

      
        Organization ID
      
      
        Role create payload.
      
      
        Create Organization Role Response
      

```python wrap showLineNumbers=false
from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole

role = CreateOrganizationRole()
role.name = "org_admin"
role.display_name = "Organization Admin"

response = scalekit_client.roles.create_organization_role('org_123456', role)
```

    
  
</div>

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

      Method to get organization role by name

      
        Organization ID
      
      
        Role name to get role details
      
      
        Get Organization Role Response
      

```python wrap showLineNumbers=false
response = scalekit_client.roles.get_organization_role('org_123456', 'org_admin')
role = response[0].role
```

    
  
</div>

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

      Method to update an existing organization role by name

      
        Organization ID
      
      
        Role name to update
      
      
        Role update payload.
      
      
        Update Organization Role Response
      

```python wrap showLineNumbers=false
from scalekit.v1.roles.roles_pb2 import UpdateRole

role = UpdateRole()
role.display_name = "Organization Administrator"

response = scalekit_client.roles.update_organization_role(
    'org_123456',
    'org_admin',
    role
)
```

    
  
</div>

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

      Method to delete organization role by name

      
        Organization ID
      
      
        Role name to be deleted
      
      
        Replacement role for users.
      
      
        Empty on success.
      

```python wrap showLineNumbers=false
scalekit_client.roles.delete_organization_role(
    'org_123456',
    'org_admin',
    reassign_role_name='member'
)
```

    
  
</div>

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

      Method to delete the base inheritance relationship for an environment-level role

      
        Role name to remove base relationship for
      
      
        Empty on success.
      

    
  
</div>

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

      Method to get the count of users associated with an organization role

      
        Organization ID
      
      
        Role name to get user count for
      
      
        Get Organization Role Users Count Response
      

    
  
</div>

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

      Method to update default organization roles

      
        Organization ID
      
      
        UpdateDefaultOrganizationRoles object with default role.
      
      
        Update Default Organization Roles Response
      

    
  
</div>

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

      Method to delete organization role base relationship by name

      
        Organization ID
      
      
        Role name to remove base relationship for
      
      
        Empty on success.
      

    
  
</div>

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

      Method to update default environment-level roles

      
        Optional. Name of the role to set as default creator role
      
      
        Optional. Name of the role to set as default member role
      
      
        Update Default Roles Response
      

    
  
</div>

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

      Method to list roles that directly extend (depend on) the specified base role

      
        Name of the base role
      
      
        List Dependent Roles Response
      

    
  
</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 |