Users API

The Users API allows you to manage user accounts, permissions, and access control on the Lumea platform.

Overview

The Users API provides comprehensive functionality for managing users within your organization on the Lumea platform. It allows administrators to create, update, and delete user accounts, as well as manage user roles and permissions. Regular users can also access their own profile information and make permitted updates.

Note: Each customer receives a custom deployment with a unique API endpoint. The endpoints described in this documentation should be prefixed with your organization's specific API URL provided during onboarding.

Data Models

User Object

Field	Type	Description
id	string	Unique identifier for the user
email	string	User's email address
name	string	User's full name
role	string	User's role (e.g., "user", "admin")

Endpoints

Create User

Creates a new user in the system. Requires admin privileges.

URL: /users

Method: POST

Auth required: Yes (Admin only)

Request Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

Field	Type	Required	Description
email	string	Yes	Valid email address
name	string	Yes	User's full name
role	string	Yes	User role (e.g., "user", "admin")

Success Response:

• Code: 200 OK
• Content:

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

Error Responses:

• Code: 400 Bad Request

  • Content: {"detail": "Email already exists"}

• Code: 403 Forbidden

  • Content: {"detail": "Unauthorized"}

List Users

Retrieves a list of all users in the system. Requires admin privileges.

URL: /users

Method: GET

Auth required: Yes (Admin only)

Success Response:

• Code: 200 OK
• Content:

[
  {
    "id": "user123",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  },
  {
    "id": "user456",
    "email": "admin@example.com",
    "name": "Jane Smith",
    "role": "admin"
  }
]

Error Response:

• Code: 403 Forbidden
  • Content: {"detail": "Unauthorized"}

Get Current User

Retrieves information about the currently authenticated user.

URL: /users/me

Method: GET

Auth required: Yes

Success Response:

• Code: 200 OK
• Content:

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "Invalid user"}

Get User by ID

Retrieves information about a specific user by their ID.

URL: /users/{user_id}

Method: GET

Auth required: Yes

URL Parameters:

Parameter	Description
user_id	The unique ID of the user

Success Response:

• Code: 200 OK
• Content:

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user"
}

Error Response:

• Code: 400 Bad Request
  • Content: {"detail": "User not found"}

Update Current User

Updates information for the currently authenticated user.

URL: /users/me

Method: PUT

Auth required: Yes

Request Body:

{
  "name": "John Smith"
}

Field	Type	Required	Description
name	string	No	User's full name

Notes:

• Regular users can only update their name
• All fields are optional. Only specified fields will be updated.

Success Response:

• Code: 200 OK
• Content:

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Smith",
  "role": "user"
}

Error Responses:

• Code: 400 Bad Request
  • Content: {"detail": "Invalid input"}

Update User by ID

Updates information for a specific user. Requires admin privileges.

URL: /users/{user_id}

Method: PUT

Auth required: Yes (Admin only)

URL Parameters:

Parameter	Description
user_id	The unique ID of the user

Request Body:

{
  "name": "John Smith",
  "email": "john.smith@example.com",
  "role": "admin"
}

Field	Type	Required	Description
email	string	No	Valid email address
name	string	No	User's full name
role	string	No	User role

Notes:

• All fields are optional. Only specified fields will be updated.

Success Response:

• Code: 200 OK
• Content:

{
  "id": "user123",
  "email": "john.smith@example.com",
  "name": "John Smith",
  "role": "admin"
}

Error Responses:

• Code: 400 Bad Request

  • Content: {"detail": "User not found"}
  • Content: {"detail": "Email already exists"}

• Code: 403 Forbidden

  • Content: {"detail": "Unauthorized"}

Delete User

Deletes a specific user from the system. Requires admin privileges.

URL: /users/{user_id}

Method: DELETE

Auth required: Yes (Admin only)

URL Parameters:

Parameter	Description
user_id	The unique ID of the user

Success Response:

• Code: 200 OK
• Content:

{
  "message": "User deleted successfully"
}

Error Responses:

• Code: 400 Bad Request

  • Content: {"detail": "User not found"}

• Code: 403 Forbidden

  • Content: {"detail": "Unauthorized"}

Authentication Endpoints

Request Login Code

Requests a login code to be sent to the specified email address.

URL: /users/request-login-code

Method: POST

Auth required: No

Request Body:

{
  "email": "user@example.com"
}

Field	Type	Required	Description
email	string	Yes	Valid email address

Notes:

• For security reasons, the API returns the same response whether the email exists or not
• Login codes expire after 10 minutes
• Each request generates a new 6-digit login code

Success Response:

• Code: 200 OK
• Content:

{
  "message": "If your email exists in our system, a login code has been sent"
}

Error Response:

• Code: 500 Internal Server Error
  • Content: {"detail": "Failed to send login code email"}

Verify Login Code

Verifies a login code and returns an access token if valid.

URL: /users/verify-login-code

Method: POST

Auth required: No

Request Body:

{
  "email": "user@example.com",
  "code": "123456"
}

Field	Type	Required	Description
email	string	Yes	Valid email address
code	string	Yes	6-digit login code

Success Response:

• Code: 200 OK
• Content:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user123",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }
}

Error Responses:

• Code: 400 Bad Request
  • Content: {"detail": "Invalid email or login code"}
  • Content: {"detail": "Login code expired"}