Users and Groups Reference

User profile, settings, shares, invitations, and admin user/group management.

Base paths: /api/v1/users/, /api/v1/admin/users/, /api/v1/admin/groups/

Current user#

GET /api/v1/users/me#

Current user's profile.

Response:

json
{
  "id": "usr_01J3N",
  "email": "alice@example.com",
  "name": "Alice Cooper",
  "display_name": "Alice",
  "tenant_id": "tnt_01J3A",
  "partner_id": "prt_01J3P",
  "groups": ["grp_01J3L"],
  "scopes": ["files:read", "files:write", "tenant:admin"],
  "is_admin": true,
  "admin_role": "tenant_admin"
}

GET /api/v1/users/me/shares#

List shares the caller has access to, with their role in each.

Query: limit (1–100, default 50), offset.

Response: {"shares": [...], "total": N}. Each share includes id, name, type, role, owner_id, quota_bytes, used_bytes, created_at.

GET /api/v1/users/me/quota#

Aggregate storage use and quota for the caller.

Response:

json
{
  "user_id": "usr_01J3N",
  "used_bytes": 42301234567,
  "quota_bytes": 107374182400,
  "percent_used": 39.4
}

GET /api/v1/users/me/stats#

Detailed per-share breakdown.

Response: Per-share {share_id, share_name, file_count, folder_count, used_bytes, trash_bytes, version_bytes}, plus tenant totals.

GET /api/v1/users/me/recent#

Recently accessed files for the caller. Placeholder — returns empty.

GET, POST, DELETE /api/v1/users/me/favorites#

Favorite files/folders. Placeholder — returns empty / accepts writes as no-ops.

GET /api/v1/users/me/invitations#

Pending invitations addressed to the caller's email.

Response: {invitations: [...]}. Each invitation: id, share_id, share_name, role, message, invited_by, expires_at.

POST /api/v1/users/me/invitations/{invitation_id}/accept#

Accept an invitation. Creates a ShareMember.

Response: {share_id, role}.

POST /api/v1/users/me/invitations/{invitation_id}/decline#

Decline an invitation.

Admin — users#

Require tenant:admin or higher.

GET /api/v1/admin/users#

List users in the tenant.

Query:

Param	Notes
`limit`	1–100, default 50
`offset`	Pagination
`search`	Match against email, name, display_name
`status`	`active`, `inactive`, `suspended`, `pending`, `deleted`
`is_admin`	Filter admins

Response: {users: [...], total: N}. Each user: id, tenant_id, email, name, display_name, avatar_url, status, is_active, is_admin, admin_role, quota_bytes, provisioning_source, scaikey_synced_at, last_login_at, created_at, group_count.

GET /api/v1/admin/users/{user_id}#

Single user with full details.

PATCH /api/v1/admin/users/{user_id}#

Update user attributes.

Body fields: email, name, display_name, avatar_url, status, is_active, is_admin, admin_role.

DELETE /api/v1/admin/users/{user_id}#

Deactivate user (soft; returns 204). Preserves content they own; they can no longer log in.

POST /api/v1/admin/users/{user_id}/activate#

Reactivate a previously deactivated user. Returns 204.

POST /api/v1/admin/users/{user_id}/sync#

Force a sync from ScaiKey for one user. Returns 202. Useful after manual directory edits.

Admin — groups#

GET /api/v1/admin/groups#

List groups.

Query: limit, offset, search.

Response: {groups: [...], total: N}. Each group: id, name, description, slug, group_type, member_count, created_at.

GET /api/v1/admin/groups/{group_id}#

Group detail with members.

Response: group fields plus members: [{id, email, name, display_name}].

POST /api/v1/admin/groups#

Create a group.

Body:

json
{
  "name": "Engineering",
  "description": "Engineering org",
  "slug": "engineering",
  "group_type": null
}

Returns 201 with the new group.

PATCH /api/v1/admin/groups/{group_id}#

Update group metadata.

DELETE /api/v1/admin/groups/{group_id}#

Delete group. Returns 204. Members remain; their group-mediated permissions disappear.

POST /api/v1/admin/groups/{group_id}/members#

Add user to group.

Body: {"user_id": "usr_01J4M"}. Returns 201.

DELETE /api/v1/admin/groups/{group_id}/members/{user_id}#

Remove user from group. Returns 204.