Users API

Manage team members and their access to Noxys programmatically. Requires admin role.

Invite User

Invite a new user to your organization.

Endpoint: POST /api/v1/users/invite

Request:

curl -X POST https://api.noxys.cloud/api/v1/users/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bob@acme.fr",
    "display_name": "Bob Martin",
    "role": "admin"
  }'

Required Fields:

Field	Type	Description
email	String	User email address (must be unique in tenant)
role	String	User role: admin or viewer

Optional Fields:

Field	Type	Description
display_name	String	Full name or display name

Response (201 Created):

{
  "id": "00000000-0000-0000-0000-000000000011",
  "tenant_id": "00000000-0000-0000-0000-000000000001",
  "email": "bob@acme.fr",
  "display_name": "Bob Martin",
  "role": "admin",
  "status": "pending",
  "created_at": "2026-03-20T10:00:00Z",
  "invited_by": "alice@acme.fr"
}

Status field values:

• pending — Invitation sent, user hasn't accepted yet
• active — User has accepted invitation and logged in
• inactive — User has been disabled

Notes:

• User receives email with invitation link
• Invitation expires after 7 days
• User must accept invitation before gaining access
• Cannot invite duplicate email addresses

List Users

Query all users in your organization.

Endpoint: GET /api/v1/users

Query Parameters:

Parameter	Type	Description
page	Integer	Page number (default: 1)
limit	Integer	Items per page (default: 50, max: 500)
role	String	Filter by role: admin or viewer
status	String	Filter by status: active, pending, inactive
sort	String	Sort field: created_at, email, with optional - for descending

Example — List All Admin Users:

curl "https://api.noxys.cloud/api/v1/users?role=admin&status=active" \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK):

{
  "users": [
    {
      "id": "00000000-0000-0000-0000-000000000010",
      "email": "alice@acme.fr",
      "display_name": "Alice Martin",
      "role": "admin",
      "status": "active",
      "created_at": "2026-01-15T09:00:00Z",
      "last_login": "2026-03-20T14:32:00Z"
    },
    {
      "id": "00000000-0000-0000-0000-000000000011",
      "email": "bob@acme.fr",
      "display_name": "Bob Martin",
      "role": "admin",
      "status": "active",
      "created_at": "2026-02-01T10:00:00Z",
      "last_login": "2026-03-19T11:00:00Z"
    }
  ],
  "total": 12
}

Get User

Retrieve a single user by ID.

Endpoint: GET /api/v1/users/:id

Example:

curl https://api.noxys.cloud/api/v1/users/00000000-0000-0000-0000-000000000011 \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK): Full user object.

Update User

Modify user details or role.

Endpoint: PUT /api/v1/users/:id

Request:

curl -X PUT https://api.noxys.cloud/api/v1/users/00000000-0000-0000-0000-000000000011 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Bob T. Martin",
    "role": "viewer"
  }'

Fields (all optional):

Field	Type	Description
display_name	String	Updated display name
role	String	New role: admin or viewer

Response (200 OK): Updated user object.

Notes:

• Cannot change email address via API (contact support to handle)
• Changing role takes effect immediately
• Cannot downgrade yourself; ask another admin to change your role

Update User Status

Enable or disable a user account.

Endpoint: PATCH /api/v1/users/:id/status

Request:

curl -X PATCH https://api.noxys.cloud/api/v1/users/00000000-0000-0000-0000-000000000011/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Status Values:

• active — User can log in
• inactive — User cannot log in (account disabled)

Response (200 OK): Updated user object with new status.

Change User Password

Reset a user's password (admin only).

Endpoint: POST /api/v1/users/:id/reset-password

Request:

curl -X POST https://api.noxys.cloud/api/v1/users/00000000-0000-0000-0000-000000000011/reset-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_password": "NewSecure123!"
  }'

Required Fields:

Field	Type	Description
new_password	String	New password (min 12 characters, mixed case and numbers)

Response (200 OK):

{
  "success": true,
  "message": "Password reset successfully"
}

Notes:

• User is logged out immediately after password change
• They must log in again with new password
• Password must meet complexity requirements

Delete User

Remove a user from your organization.

Endpoint: DELETE /api/v1/users/:id

Example:

curl -X DELETE https://api.noxys.cloud/api/v1/users/00000000-0000-0000-0000-000000000011 \
  -H "Authorization: Bearer $TOKEN"

Response (204 No Content) — No response body.

Notes:

• Deletion is immutable (user cannot be restored)
• User's data (interactions, alerts) remains in audit log for compliance
• Cannot delete yourself; ask another admin
• User is logged out immediately

Get Current User

Retrieve info about the authenticated user.

Endpoint: GET /api/v1/users/me

Example:

curl https://api.noxys.cloud/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK):

{
  "id": "00000000-0000-0000-0000-000000000010",
  "email": "alice@acme.fr",
  "display_name": "Alice Martin",
  "role": "admin",
  "status": "active",
  "tenant_id": "00000000-0000-0000-0000-000000000001",
  "created_at": "2026-01-15T09:00:00Z",
  "last_login": "2026-03-20T14:32:00Z"
}

Update Current User

Update your own profile.

Endpoint: PUT /api/v1/users/me

Request:

curl -X PUT https://api.noxys.cloud/api/v1/users/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Alice T. Martin"
  }'

Fields (all optional):

Field	Type	Description
display_name	String	Updated display name
password	String	New password (if changing)

Response (200 OK): Updated user object.

Code Examples

Python: Invite and Manage Users

import requests

BASE_URL = "https://api.noxys.cloud/api/v1"
TOKEN = "eyJhbGc..."
headers = {"Authorization": f"Bearer {TOKEN}"}

# 1. Invite a new user
user_data = {
    "email": "charlie@acme.fr",
    "display_name": "Charlie Smith",
    "role": "viewer"
}

response = requests.post(f"{BASE_URL}/users/invite", headers=headers, json=user_data)
user_id = response.json()["id"]
print(f"Invited user: {response.json()['email']} (status: {response.json()['status']})")

# 2. List all active users
response = requests.get(f"{BASE_URL}/users?status=active&limit=100", headers=headers)
users = response.json()["users"]
print(f"\nTotal active users: {len(users)}")
for user in users:
    print(f"  {user['email']} ({user['role']})")

# 3. Update user role
update_data = {"role": "admin"}
response = requests.put(f"{BASE_URL}/users/{user_id}", headers=headers, json=update_data)
print(f"\nUpdated {response.json()['email']} role to {response.json()['role']}")

# 4. Disable user
disable_data = {"status": "inactive"}
response = requests.patch(
    f"{BASE_URL}/users/{user_id}/status",
    headers=headers,
    json=disable_data
)
print(f"Disabled user: {response.json()['status']}")

# 5. Get current user
response = requests.get(f"{BASE_URL}/users/me", headers=headers)
current_user = response.json()
print(f"\nYou are: {current_user['email']} ({current_user['role']})")

# 6. Delete user
requests.delete(f"{BASE_URL}/users/{user_id}", headers=headers)
print("User deleted")

Go: Bulk User Management

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const BaseURL = "https://api.noxys.cloud/api/v1"

type UserInvite struct {
    Email       string `json:"email"`
    DisplayName string `json:"display_name"`
    Role        string `json:"role"`
}

type UserUpdate struct {
    DisplayName string `json:"display_name,omitempty"`
    Role        string `json:"role,omitempty"`
}

func inviteUsers(token string, emails []string) error {
    for _, email := range emails {
        invite := UserInvite{
            Email:       email,
            DisplayName: email,
            Role:        "viewer",
        }

        payload, _ := json.Marshal(invite)

        req, _ := http.NewRequest("POST", BaseURL+"/users/invite", bytes.NewReader(payload))
        req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", token))
        req.Header.Set("Content-Type", "application/json")

        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            return err
        }
        defer resp.Body.Close()

        if resp.StatusCode == 201 {
            fmt.Printf("Invited: %s\n", email)
        } else {
            body, _ := io.ReadAll(resp.Body)
            fmt.Printf("Error inviting %s: %s\n", email, string(body))
        }
    }
    return nil
}

func main() {
    token := "eyJhbGc..."

    emails := []string{
        "user1@acme.fr",
        "user2@acme.fr",
        "user3@acme.fr",
    }

    inviteUsers(token, emails)
}

User Roles

Admin

Full administrative access:

• Invite and manage users
• Create and delete policies
• View all interactions and alerts
• Access audit log
• Manage organization settings
• Configure webhooks and integrations
• View billing information

Viewer

Read-only access:

• View dashboard and statistics
• View interactions and alerts
• View policies (cannot modify)
• View team member list
• Cannot make any modifications

Best Practices

1. Principle of Least Privilege — Give users the minimum role needed
2. Regular Audits — Review user list quarterly; remove inactive users
3. Strong Passwords — Enforce 12+ characters, mixed case, numbers
4. Disable Instead of Delete — Use status=inactive to preserve audit history
5. Document Changes — Note reason for role/status changes in your records
6. Monitor Access — Check last_login to identify inactive accounts

What's Next?

• Tenants API — Manage organization settings
• Audit Log — View all admin actions