> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# User Management
> Manage users for your Canvas app with Clerk organizations. Invite members, assign roles, and control access — all through the API or Studio.
## Overview
Each Canvas app with Clerk authentication gets a dedicated **Clerk organization**. This organization is the single source of truth for who has access to the app and what role they hold.
User management lets you:
* **List members** of a Canvas app
* **Invite users** by email with a specific role
* **Update roles** (admin or member)
* **Remove users** to revoke access immediately
* **Manage invitations** — list pending and revoke unused invitations
User management requires `auth_config.mode` set to `"clerk"`. Apps using `public`, `password`, or other auth modes do not have per-user access control.
***
## Enabling User Management
Set your app's auth mode to `clerk`. Mixpeek automatically provisions a Clerk organization for the app:
```python Python theme={null}
from mixpeek import Mixpeek
client = Mixpeek(api_key="your-api-key")
client.apps.update(
app_id="app_abc123",
auth_config={"mode": "clerk"},
)
```
```bash cURL theme={null}
curl -X PATCH https://api.mixpeek.com/v1/apps/$APP_ID \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID" \
-H "Content-Type: application/json" \
-d '{"auth_config": {"mode": "clerk"}}'
```
Once enabled, the **Users** tab appears in the Studio app detail page.
***
## Roles
Each member has one of two roles:
| Role | Slug | Description |
| ---------- | ------------ | ------------------------------------- |
| **Member** | `org:member` | Standard access to the app |
| **Admin** | `org:admin` | Full access including user management |
***
## API Reference
All user management endpoints are scoped to a single app and require your API key with namespace header.
### List Members
Returns all users in the app's Clerk organization.
```bash theme={null}
curl https://api.mixpeek.com/v1/apps/$APP_ID/users \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID"
```
**Response:**
```json theme={null}
{
"users": [
{
"user_id": "user_abc123",
"membership_id": "mem_xyz789",
"email": "jane@example.com",
"name": "Jane Smith",
"avatar_url": "https://img.clerk.com/...",
"role": "org:admin",
"joined_at": "2026-03-15T10:30:00Z"
}
],
"total": 1
}
```
### Invite a User
Send an email invitation to join the app's organization.
```python Python theme={null}
import httpx
resp = httpx.post(
f"https://api.mixpeek.com/v1/apps/{app_id}/users/invite",
headers={
"Authorization": f"Bearer {api_key}",
"X-Namespace": namespace_id,
},
json={
"email_address": "newuser@example.com",
"role": "org:member",
},
)
print(resp.json())
```
```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/apps/$APP_ID/users/invite \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"email_address": "newuser@example.com",
"role": "org:member"
}'
```
**Response:**
```json theme={null}
{
"invitation_id": "inv_abc123",
"email_address": "newuser@example.com",
"role": "org:member",
"status": "pending",
"created_at": "2026-03-27T14:00:00Z"
}
```
### Update a User's Role
Change a member's role between `org:member` and `org:admin`.
```bash theme={null}
curl -X PATCH https://api.mixpeek.com/v1/apps/$APP_ID/users/$USER_ID/role \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID" \
-H "Content-Type: application/json" \
-d '{"role": "org:admin"}'
```
### Remove a User
Immediately revokes the user's access to the app.
```bash theme={null}
curl -X DELETE https://api.mixpeek.com/v1/apps/$APP_ID/users/$USER_ID \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID"
```
### List Pending Invitations
```bash theme={null}
curl https://api.mixpeek.com/v1/apps/$APP_ID/users/invitations \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID"
```
**Response:**
```json theme={null}
{
"invitations": [
{
"invitation_id": "inv_abc123",
"email_address": "pending@example.com",
"role": "org:member",
"status": "pending",
"created_at": "2026-03-27T14:00:00Z"
}
],
"total": 1
}
```
### Revoke an Invitation
Cancel a pending invitation before the recipient accepts it.
```bash theme={null}
curl -X DELETE https://api.mixpeek.com/v1/apps/$APP_ID/users/invitations/$INVITATION_ID \
-H "Authorization: Bearer $API_KEY" \
-H "X-Namespace: $NAMESPACE_ID"
```
***
## Studio
When a Canvas app has `auth_config.mode = "clerk"`, a **Users** tab appears in the app detail page. From there you can:
1. **View members** — see all users with their name, email, avatar, and role
2. **Invite users** — click **Invite**, enter an email and role, then send
3. **Change roles** — use the role dropdown next to any member
4. **Remove users** — click the trash icon with a confirmation dialog
5. **Manage invitations** — view pending invitations and revoke them
***
## How It Works
Each Canvas app maps to a **Clerk organization**. When you enable `auth_config.mode = "clerk"`, Mixpeek auto-provisions a Clerk org and stores the `clerk_org_id` in the app record.
All user management operations go directly to Clerk — there is no separate user database to maintain. Clerk is the single source of truth.
```
Your App (auth_config.mode = "clerk")
└── Clerk Organization (auto-provisioned)
├── Members (org:admin, org:member)
└── Pending Invitations
```
Removing a user revokes access immediately. The user will be signed out on their next request.
***
## Related
* [Authentication](/canvas/apps/authentication) — enable Clerk auth and use the MixpeekAuth SDK
* [Apps overview](/canvas/apps) — Canvas app architecture and quickstart
* [Custom Domains](/canvas/apps/domains) — add your own domain to a Canvas app