Authentication & Users

API endpoints for user authentication, facility users, and session management

User Authentication

Create Session (Login)

Authenticate a user and create a new session.

POST /api/auth/session

curl -X POST http://localhost:8080/api/auth/session \
  -H "Content-Type: application/json" \
  -d '{
    "username": "learner1",
    "password": "password123",
    "facility": "facility-uuid-here"
  }'

Request Parameters

username · string · required

Username of the user to authenticate

password · string · required

User’s password

facility · string · required

UUID of the facility the user belongs to

user_id · string

Alternative to username - UUID of the user

auth_token · string

Authentication token (used with user_id)

Response Fields

id · string

Session identifier (always “current”)

username · string

Authenticated user’s username

full_name · string

User’s full name

facility · string

UUID of the user’s facility

kind · array

Array of user roles/kinds

is_superuser · boolean

Whether the user has superuser permissions

Update Session

Update an existing session to keep it alive.

PUT /api/auth/session/current

curl -X PUT http://localhost:8080/api/auth/session/current \
  -H "Content-Type: application/json" \
  -d '{
    "active": true
  }'

Delete Session (Logout)

End the current user session.

DELETE /api/auth/session/current

curl -X DELETE http://localhost:8080/api/auth/session/current

Facility Users

List Facility Users

Retrieve a list of facility users with filtering and search capabilities.

GET /api/auth/facilityuser

curl http://localhost:8080/api/auth/facilityuser?member_of=classroom-uuid

Query Parameters

member_of · string

Filter users by collection (classroom or facility) membership

user_type · string

Filter by user type: learner, coach, admin, superuser

search · string

Search by username or full name

page_size · integer

Number of results per page

page · integer

Page number for pagination

Response Fields

id · string

User’s unique identifier

username · string

User’s username

full_name · string

User’s full name

facility · string

UUID of the user’s facility

roles · array

Array of role objects with collection, kind, and id

is_superuser · boolean

Whether user has superuser permissions

gender · string

User’s gender

birth_year · string

User’s birth year

date_joined · string

ISO 8601 timestamp of when user joined

Get Facility User

Retrieve details of a specific facility user.

GET /api/auth/facilityuser/:id

curl http://localhost:8080/api/auth/facilityuser/user-uuid-here

Create Facility User

Create a new facility user.

POST /api/auth/facilityuser

curl -X POST http://localhost:8080/api/auth/facilityuser \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newlearner",
    "full_name": "New Learner",
    "password": "password123",
    "facility": "facility-uuid-here"
  }'

Request Parameters

username · string · required

Unique username for the user

full_name · string · required

User’s full name

password · string · required

User’s password

facility · string · required

UUID of the facility

gender · string

User’s gender

birth_year · string

User’s birth year

Update Facility User

Update an existing facility user.

PATCH /api/auth/facilityuser/:id

curl -X PATCH http://localhost:8080/api/auth/facilityuser/user-uuid-here \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Updated Name"
  }'

Delete Facility User

Soft delete a facility user (marks as deleted, doesn’t remove from database).

DELETE /api/auth/facilityuser/:id

curl -X DELETE http://localhost:8080/api/auth/facilityuser/user-uuid-here

User Sign Up

Sign Up New User

Allow users to self-register if facility settings permit.

POST /api/auth/signup

curl -X POST http://localhost:8080/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "full_name": "New User",
    "password": "password123",
    "facility": "facility-uuid-here"
  }'

Username Availability

Check Username

Check if a username is available in a facility.

POST /api/auth/usernameavailable

curl -X POST http://localhost:8080/api/auth/usernameavailable \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "facility": "facility-uuid-here"
  }'

Request Parameters

username · string · required

Username to check

facility · string · required

Facility UUID to check within

Response

Returns true if username is available, or error array if already exists.