Authentication

Overview

Kolibri uses session-based authentication for the API. Users authenticate by creating a session, which is maintained via session cookies. The authentication system supports multiple methods including username/password, token-based authentication, and OS user integration.

Authentication Methods

Session Authentication (Primary)

Kolibri uses Django session authentication as the primary authentication mechanism. After successful login, the server sets a session cookie that is included in subsequent requests.

Token Authentication

Kolibri also supports token-based authentication using user_id and auth_token for specific use cases such as automatic login links.

OS User Authentication

When running in app context, Kolibri supports automatic authentication for OS users via app authentication tokens.

Base URL

All authentication endpoints are under:

/api/auth/

curl -X POST http://localhost:8000/api/auth/session/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password",
    "facility": "facility-id-here"
  }'

Request Body

username

string

Username of the user to authenticate. Required for username/password authentication.

password

string

User’s password. Can be an empty string if the facility allows passwordless login for learners.

facility

string

UUID of the facility the user belongs to. If not provided, defaults to the default facility.

user_id

string

UUID of the user (alternative to username for token authentication).

auth_token

string

Authentication token for token-based login.

Response

string

Session identifier (always “current” for the current session).

username

string

The authenticated user’s username.

full_name

string

The user’s full name.

user_id

string

UUID of the authenticated user.

facility_id

string

UUID of the user’s facility.

kind

array

Array of user types (e.g., ["admin"], ["learner"], ["coach"]).

can_manage_content

boolean

Whether the user has permission to manage content.

is_superuser

boolean

Whether the user is a device superuser.

server_time

string

Current server time in ISO 8601 format.

app_context

boolean

Whether the request is in app context.

Example Success Response (200 OK):

{
  "id": "current",
  "username": "admin",
  "full_name": "Admin User",
  "user_id": "a1b2c3d4e5f6",
  "facility_id": "f1a2c3i4l5i6",
  "kind": ["admin"],
  "can_manage_content": true,
  "is_superuser": false,
  "server_time": "2024-03-15T10:30:00Z",
  "app_context": false
}

Error Responses

Invalid Credentials (401 Unauthorized):

[
  {
    "id": "INVALID_CREDENTIALS",
    "metadata": {}
  }
]

Username Not Found (400 Bad Request):

[
  {
    "id": "NOT_FOUND",
    "metadata": {
      "field": "username",
      "message": "Username not found."
    }
  }
]

Missing Password (400 Bad Request):

[
  {
    "id": "MISSING_PASSWORD",
    "metadata": {
      "field": "password",
      "message": "Username is valid, but password is missing."
    }
  }
]

Password Not Set (400 Bad Request): Returned when a learner account requires a password to be set before login.

[
  {
    "id": "PASSWORD_NOT_SPECIFIED",
    "metadata": {
      "field": "password",
      "message": "Username is valid, but password needs to be set before login."
    }
  }
]

Get Current Session

Retrieve information about the current session.

curl http://localhost:8000/api/auth/session/current/ \
  -H "Cookie: sessionid=<session-cookie>"

Response (200 OK): Returns the same session object as the login response, including updated server_time.

Update Session

Update session activity and log user session data.

curl -X PUT http://localhost:8000/api/auth/session/current/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=<session-cookie>" \
  -d '{
    "active": true,
    "os": "Windows 10",
    "browser": "Chrome 120"
  }'

active

boolean

default:"false"

Whether the user is currently active. When true, updates the user session log.

string

Operating system information for session logging.

browser

string

Browser information for session logging.

Response (200 OK): Returns updated session data.

Logout (Destroy Session)

End the current session and log out the user.

curl -X DELETE http://localhost:8000/api/auth/session/current/ \
  -H "Cookie: sessionid=<session-cookie>"

Response (200 OK):

[]

The session cookie will be invalidated, and subsequent requests will be treated as anonymous.

Set Password for Passwordless Account

Set a password for a learner account that was created without one (when passwordless login was enabled).

curl -X POST http://localhost:8000/api/auth/setnonspecifiedpassword/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "learner1",
    "password": "newpassword",
    "facility": "facility-id-here"
  }'

username

string

required

Username of the learner account.

password

string

required

New password to set for the account.

facility

string

required

UUID of the facility the user belongs to.

Response (200 OK): Returns an empty response on success. Error Response (404 Not Found):

"Suitable user does not exist"

Returned if:

The user doesn’t exist
The user already has a password set
The user is an OS user

Check Username Availability

Check if a username is available for registration in a specific facility.

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

username

string

required

Username to check for availability.

facility

string

required

UUID of the facility to check within.

Success Response (200 OK):

true

Username Exists (400 Bad Request):

[
  {
    "id": "USERNAME_ALREADY_EXISTS",
    "metadata": {
      "field": "username",
      "message": "Username already exists."
    }
  }
]

Create a new learner account in a facility that allows self-registration.

curl -X POST http://localhost:8000/api/auth/signup/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newlearner",
    "password": "password123",
    "full_name": "New Learner",
    "facility": "facility-id-here",
    "gender": "MALE",
    "birth_year": "2010"
  }'

username

string

required

Desired username (must be unique within the facility).

password

string

required

User’s password.

full_name

string

required

User’s full name.

facility

string

required

UUID of the facility to join.

gender

string

User’s gender. Options: "MALE", "FEMALE", "NOT_SPECIFIED", or "DEFERRED".

birth_year

string

User’s birth year as a string (e.g., "2010").

Response (201 Created): Returns the created user object and automatically logs the user in (sets session cookie).

{
  "id": "new-user-id",
  "username": "newlearner",
  "full_name": "New Learner",
  "facility": "facility-id-here",
  "gender": "MALE",
  "birth_year": "2010",
  "roles": [],
  "is_superuser": false
}

Error Response (403 Forbidden):

"Cannot sign up to this facility"

Returned if:

The facility does not allow learner self-registration (learner_can_sign_up is false)
The facility is not a full facility import

Authentication Flow Example

Here’s a complete authentication flow example:

// 1. Get CSRF token
const sessionResponse = await fetch('/api/auth/session/current/');
const csrfToken = sessionResponse.headers.get('X-CSRFToken');

// 2. Login
const loginResponse = await fetch('/api/auth/session/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRFToken': csrfToken
  },
  body: JSON.stringify({
    username: 'admin',
    password: 'password',
    facility: facilityId
  })
});

const session = await loginResponse.json();
console.log('Logged in as:', session.username);

// 3. Make authenticated requests
const usersResponse = await fetch('/api/auth/facilityuser/', {
  headers: {
    'X-CSRFToken': csrfToken
  }
});

const users = await usersResponse.json();

// 4. Logout
await fetch('/api/auth/session/current/', {
  method: 'DELETE',
  headers: {
    'X-CSRFToken': csrfToken
  }
});

Anonymous Access

Some endpoints allow anonymous (unauthenticated) access depending on facility settings:

Public facility information
Public content metadata
Sign up endpoints (when enabled)

Anonymous users receive a visitor_id cookie for tracking purposes but have limited permissions.

Session Timeout

Sessions expire after a period of inactivity. The timeout duration is configurable. To prevent timeout:

Periodically send PUT requests to /api/auth/session/current/ with active: true
The last_session_request timestamp is updated on each request

Security Considerations

HTTPS in Production: Always use HTTPS in production to protect credentials in transit
CSRF Protection: Include CSRF tokens in all state-changing requests
Password Strength: Enforce strong passwords at the application level
Session Security: Configure secure session cookies with HttpOnly and Secure flags
Rate Limiting: Implement rate limiting on login endpoints to prevent brute force attacks

Permissions - Understanding user roles and permissions
Facility Management - Managing facilities and facility settings
User Management - CRUD operations on user accounts

Core APIs

Resources

Frontend

Overview

Authentication Methods

Session Authentication (Primary)

Token Authentication

OS User Authentication

Base URL

Request Body

Response

Error Responses

Get Current Session

Update Session

Logout (Destroy Session)

Set Password for Passwordless Account

Check Username Availability

Authentication Flow Example

Anonymous Access

Session Timeout

Security Considerations

Build docs developers (and LLMs) love

Core APIs

Resources

Frontend

​Overview

​Authentication Methods

​Session Authentication (Primary)

​Token Authentication

​OS User Authentication

​Base URL

​Create Session (Login)

​Request Body

​Response

​Error Responses

​Get Current Session

​Update Session

​Logout (Destroy Session)

​Set Password for Passwordless Account

​Check Username Availability

​User Sign Up

​Authentication Flow Example

​Anonymous Access

​Session Timeout

​Security Considerations

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Authentication Methods

Session Authentication (Primary)

Token Authentication

OS User Authentication

Base URL

Create Session (Login)

Request Body

Response

Error Responses

Get Current Session

Update Session

Logout (Destroy Session)

Set Password for Passwordless Account

Check Username Availability

User Sign Up

Authentication Flow Example

Anonymous Access

Session Timeout

Security Considerations

Related Endpoints