APIIdentity & Access
Users API
The Users API provides CRUD operations for managing platform users within a tenant. All endpoints are scoped to the authenticated user's tenant_id from the JWT — cross-tenant access is not possible.
Endpoints
| Method | Path | Description | Required Permission |
|---|---|---|---|
| GET | /users | List all users in the tenant (paginated) | iam:read |
| GET | /users/{id} | Get a single user by ID | iam:read |
| POST | /users | Create a new user (sends Auth0 invite) | iam:write |
| PUT | /users/{id} | Update user profile, role, or group membership | iam:write |
| DELETE | /users/{id} | Deactivate and remove user from tenant | iam:admin |
User Object
User Response Object
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "jane.doe@acme.com",
"name": "Jane Doe",
"role_id": "role_analyst",
"group_ids": ["grp_data_team", "grp_finops"],
"created_at": "2024-01-15T09:30:00Z",
"last_login": "2024-03-01T14:22:00Z",
"is_active": true
}Create User Request Body
POST /users — Request Body
{
"email": "new.user@acme.com",
"name": "New User",
"role_id": "role_analyst",
"group_ids": ["grp_data_team"]
}User Fields Reference
| Field | Type | Description |
|---|---|---|
| id | string (UUID) | Unique identifier for the user |
| string | User's email address. Must be unique within the tenant. Used for Auth0 invite. | |
| name | string | Display name shown in the UI |
| role_id | string | The role assigned directly to this user. Used as the base permission set. |
| group_ids | string[] | Array of group IDs the user belongs to. Groups may grant additional permissions. |
| created_at | string (ISO 8601) | Timestamp when the user was created |
| is_active | boolean | Whether the user can log in. Set to false to deactivate without deleting. |
Permission Resolution
A user's effective permissions are resolved in the following priority order (highest to lowest):
- User-level overrides — explicit permissions set directly on the user record. These always take precedence.
- Group permissions — the union of permissions from all groups the user belongs to.
- Role permissions — the permission set defined by the user's assigned
role_id. - Global defaults — tenant-level default permissions applied to all users without a specific role.
Permission Resolution
User-level overrides take precedence over group permissions, which take precedence over role permissions. This means a user can be granted or restricted from specific permissions independently of their group or role assignment.