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

---

# Users

Provision and manage users and memberships
<div class="sdk-client-page">

Use the `user` client to provision people, manage organization memberships, and assign roles.

Common flows: invite or create a user, attach them to an organization, update profile fields, and look up users by Scalekit ID or your external ID.

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

      Creates a new user and adds them as a member of an organization in a single operation.

      
        The organization ID to add the user to
      
      
        Optional request settings.
      
      
        The created resource.
      

```typescript wrap showLineNumbers=false
const response = await scalekit.user.createUserAndMembership(
  'org_123456',
  {
    email: 'john.doe@company.com',
    userProfile: {
      firstName: 'John',
      lastName: 'Doe'
    },
    sendInvitationEmail: true,
    metadata: {
      department: 'Engineering'
    }
  }
);

console.log('User created:', response.user.id);
```

    
  
</div>

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

      Retrieves comprehensive details about a specific user including their profile and memberships.

      
        Scalekit user ID (`usr_...`).
      
      
        The user.
      

```typescript wrap showLineNumbers=false
const response = await scalekit.user.getUser('usr_123456');
const user = response.user;

console.log('User:', user.email);
console.log('Name:', user.userProfile?.firstName, user.userProfile?.lastName);
console.log('Organizations:', user.memberships?.length);
```

    
  
</div>

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

      Retrieves a paginated list of all users across your Scalekit environment.

      
        Optional fields: `pageSize`, `pageToken`.
      
      
        Paginated users.
      

```typescript wrap showLineNumbers=false
// pageSize: Results per page (default 10, max 100)
// pageToken: Token for the next page
const response = await scalekit.user.listUsers({
  pageSize: 20
});

console.log('Users:', response.users.length);
console.log('Total users:', response.totalSize);
```

    
  
</div>

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

      Updates a user's profile information and custom metadata.

      
        The Scalekit user identifier (format: "usr_...")
      
      
        Fields to update.
      
      
        The updated user.
      

```typescript wrap showLineNumbers=false
// metadata: Custom key-value metadata
const response = await scalekit.user.updateUser('usr_123456', {
  userProfile: {
    firstName: 'John',
    lastName: 'Smith'
  },
  metadata: {
    department: 'Engineering',
    title: 'Senior Developer'
  }
});
```

    
  
</div>

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

      Permanently deletes a user from your Scalekit environment.

      
        Scalekit user ID (`usr_...`).
      
      
        Empty response on successful deletion
      

```typescript wrap showLineNumbers=false
await scalekit.user.deleteUser('usr_123456');
console.log('User deleted successfully');
```

    
  
</div>

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

      Adds an existing user as a member of a new organization with specified roles.

      
        Organization ID.
      
      
        The user ID to add as a member (format: "usr_...")
      
      
        Optional fields: `roles`, `metadata`, `sendInvitationEmail`.
      
      
        The created resource.
      

```typescript wrap showLineNumbers=false
// roles: Assigned roles
// sendInvitationEmail: send invitation email
const response = await scalekit.user.createMembership(
  'org_123456',
  'usr_789012',
  {
    roles: ['admin'],
    sendInvitationEmail: true
  }
);
```

    
  
</div>

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

      Removes a user's membership from a specific organization.

      
        Organization ID.
      
      
        The user ID to remove (format: "usr_...")
      
      
        Empty response on successful removal
      

```typescript wrap showLineNumbers=false
await scalekit.user.deleteMembership('org_123456', 'usr_789012');
console.log('User removed from organization');
```

    
  
</div>

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

      Updates a user's roles and metadata within a specific organization.

      
        Organization ID.
      
      
        Scalekit user ID (`usr_...`).
      
      
        Optional fields: `roles`, `metadata`.
      
      
        The updated resource.
      

```typescript wrap showLineNumbers=false
// roles: Assigned roles
const response = await scalekit.user.updateMembership(
  'org_123456',
  'usr_789012',
  { roles: ['admin'] }
);
```

    
  
</div>

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

      Retrieves a paginated list of all users who are members of a specific organization.

      
        Organization ID.
      
      
        Optional fields: `pageSize`, `pageToken`.
      
      
        Paginated users.
      

```typescript wrap showLineNumbers=false
// pageSize: Results per page (default 10, max 100)
// pageToken: Token for the next page
const response = await scalekit.user.listOrganizationUsers('org_123456', {
  pageSize: 25
});

console.log('Organization users:', response.users.length);
console.log('Total members:', response.totalSize);
```

    
  
</div>

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

      Resends an invitation email to a user for a specific organization.

      
        The organization ID for which to resend the invite.
      
      
        Scalekit user ID (`usr_...`).
      
      
        Resend invite.
      

```typescript wrap showLineNumbers=false
const response = await scalekit.user.resendInvite('org_123456', 'usr_789012');
console.log('Invitation resent:', response.invite);
```

    
  
</div>

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

      Lists all roles assigned to a user within a specific organization.

      
        Organization ID.
      
      
        The user ID whose roles to list (format: "usr_...")
      
      
        Paginated roles.
      

    
  
</div>

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

      Lists all effective permissions for a user within a specific organization.

      
        Organization ID.
      
      
        Scalekit user ID (`usr_...`).
      
      
        Paginated permissions.
      

    
  
</div>

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

      Searches for users matching a query string across the environment.

      
        Search query string
      
      
        Optional. Number of results per page
      
      
        Optional. Pagination token for the next page
      
      
        Paginated results.
      

    
  
</div>

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

      Searches for users matching a query string within a specific organization.

      
        The organization ID to search within
      
      
        Search query string
      
      
        Optional. Number of results per page
      
      
        Optional. Pagination token for the next page
      
      
        Paginated results.
      

    
  
</div>

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

      Assigns roles to a user within a specific organization.

      
        The organization ID
      
      
        The user ID to assign roles to
      
      
        Array of role names to assign
      
      
        Assign user roles.
      

    
  
</div>

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

      Removes a specific role from a user within an organization.

      
        The organization ID
      
      
        The user ID to remove the role from
      
      
        The name of the role to remove
      
      
        Empty response on success
      

    
  
</div>

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

      Retrieves a user by their external ID.

      
        The external identifier for the user
      
      
        The user.
      

    
  
</div>

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

      Updates a user identified by their external ID.

      
        The external identifier for the user
      
      
        Fields to update.
      
      
        The updated user.
      

    
  
</div>

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

      Permanently deletes a user identified by their external ID.

      
        The external identifier for the user
      
      
        Empty response on success
      

    
  
</div>

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

      Adds a user identified by external ID as a member of an organization.

      
        The organization ID to add the user to
      
      
        The external identifier for the user
      
      
        Optional fields: `roles`, `metadata`, `sendInvitationEmail`.
      
      
        The created resource.
      

    
  
</div>

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

      Removes the membership of a user identified by external ID from an organization.

      
        The organization ID to remove the user from
      
      
        The external identifier for the user
      
      
        Empty response on success
      

    
  
</div>

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

      Updates the membership of a user identified by external ID within an organization.

      
        The organization ID where the membership exists
      
      
        The external identifier for the user
      
      
        Optional fields: `roles`, `metadata`.
      
      
        The updated resource.
      

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