Users & permissions API

Create and manage user accounts, permission overrides, and invite tokens.

List users

httpCopy
GET /api/users
Authorization: Bearer {token}
# MSP: returns all users (filterable by ?tenant_id=5)
# Client: returns users in current tenant only

Create user

httpCopy
POST /api/users
Authorization: Bearer {token}
Content-Type: application/json

{{
  "name": "Alice Smith",
  "email": "[email protected]",
  "password": "securepassword123",
  "role_id": 3,          # 1=msp_admin, 2=msp_tech, 3=client_admin, 4=client_mgr, 5=client_viewer
  "tenant_id": 5,        # null for MSP staff
  "is_msp_staff": false,
  "active": true
}}

Update user

httpCopy
PUT /api/users/{id}
Authorization: Bearer {token}
Content-Type: application/json

# Same body as create.
# Omit "password" to keep the existing password unchanged.
# Include "password" to reset it.

Delete user

httpCopy
DELETE /api/users/{id}
Authorization: Bearer {token}
# Permanently deletes the account.
# Their name remains in checkout history records.

List roles

httpCopy
GET /api/users/roles/all
Authorization: Bearer {token}

# Returns:
[
  {{"id": 1, "name": "msp_admin", "display_name": "MSP Admin"}},
  {{"id": 2, "name": "msp_technician", "display_name": "MSP Technician"}},
  {{"id": 3, "name": "client_admin", "display_name": "Client Admin"}},
  {{"id": 4, "name": "client_manager", "display_name": "Client Manager"}},
  {{"id": 5, "name": "client_viewer", "display_name": "Client Viewer"}}
]

Get user permissions

httpCopy
GET /api/users/{id}/permissions
Authorization: Bearer {token}

# Returns:
{{
  "role_permissions": ["assets.view", "assets.create", ...],
  "overrides": [
    {{"permission_key": "assets.delete", "granted": false}}
  ],
  "effective_permissions": ["assets.view", "assets.create", ...]
}}

Set permission override

httpCopy
PUT /api/users/{id}/permissions
Authorization: Bearer {token}
Content-Type: application/json

{{
  "permission_key": "assets.delete",
  "granted": false   # false = revoke; true = grant
}}

# Returns the updated effective permissions

Clear permission override

httpCopy
DELETE /api/users/{id}/permissions/{permission_key}
Authorization: Bearer {token}
# Removes the override — user falls back to role default

Invites

httpCopy
# Create invite
POST /api/invites
Authorization: Bearer {token}
Content-Type: application/json
{{
  "email": "[email protected]",
  "name": "New User",
  "role_id": 3,
  "tenant_id": 5,
  "expires_hours": 72
}}
# Returns: {{"token": "...", "invite_url": "https://acme.atechsolutions.org/invite/..."}}

# List pending invites
GET /api/invites
Authorization: Bearer {token}

# Validate a token (public — no auth)
GET /api/invites/validate/{token}

# Accept an invite (public — no auth)
POST /api/invites/accept
Content-Type: application/json
{{
  "token": "abc123...",
  "name": "Alice Smith",
  "password": "securepassword123"
}}

# Revoke an invite
DELETE /api/invites/{id}
Authorization: Bearer {token}