Skip to main content
The Sakai REST API requires authentication for all endpoints. Authentication is handled through session-based cookies established via the login endpoint.

​
Authentication Flow

1

Login Request

Send credentials to the /api/login endpoint to establish a session
2

Session Cookie

Receive a session cookie (JSESSIONID) in the response
3

Authenticated Requests

Include the session cookie in subsequent API requests
4

Logout

Call /api/logout to terminate the session when done

​
Login Endpoint

​
POST /api/login
endpoint
Authenticate a user and establish a session

​
Request

Content-Type: application/x-www-form-urlencoded Parameters:
  • username (required) - User’s username or email
  • password (required) - User’s password
Example: 
curl -X POST https://your-sakai-instance.edu/api/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=your-password" \
  -c cookies.txt

​
Response

Success (200 OK): 
{
  "status": "success",
  "userId": "user-id-123",
  "sessionId": "session-id-456",
  "displayName": "John Instructor"
}
The response includes a Set-Cookie header with the session cookie: 
Set-Cookie: JSESSIONID=abc123...; Path=/; HttpOnly; Secure
Failure (401 Unauthorized): 
{
  "error": {
    "status": "401",
    "message": "Invalid credentials"
  }
}
Source: webapi/src/main/java/org/sakaiproject/webapi/controllers/LoginController.java

​
Session Management

The JSESSIONID cookie must be included in all authenticated requests: 
curl https://your-sakai-instance.edu/api/users/me/announcements \
  -b cookies.txt

​
Session Timeout

Sessions timeout after a period of inactivity (typically 30 minutes). The timeout is configured in sakai.properties: 
# Session timeout in seconds (default: 1800 = 30 minutes)
session.timeout=1800
Always implement session refresh logic in long-running applications to avoid timeout errors.

​
Session Validation

All REST controllers extend AbstractSakaiApiController, which provides the checkSakaiSession() method to validate the current session: 
protected void checkSakaiSession() throws UserNotDefinedException {
    String sessionId = sessionManager.getCurrentSessionUserId();
    if (sessionId == null) {
        throw new UserNotDefinedException("No valid session");
    }
}
Source: webapi/src/main/java/org/sakaiproject/webapi/controllers/AbstractSakaiApiController.java

​
Making Authenticated Requests

Once authenticated, include the session cookie in all requests: 
# Get current user's announcements
curl https://your-sakai-instance.edu/api/users/me/announcements \
  -b cookies.txt

​
JavaScript Fetch Example

// Login
const loginResponse = await fetch('https://your-sakai-instance.edu/api/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: '[email protected]&password=secret',
  credentials: 'include' // Important: include cookies
});

if (loginResponse.ok) {
  // Make authenticated requests
  const announcementsResponse = await fetch(
    'https://your-sakai-instance.edu/api/users/me/announcements',
    {
      credentials: 'include' // Include session cookie
    }
  );
  
  const data = await announcementsResponse.json();
  console.log(data);
}

​
Python Example

import requests

# Create a session to persist cookies
session = requests.Session()

# Login
login_data = {
    'username': '[email protected]',
    'password': 'secret'
}
login_response = session.post(
    'https://your-sakai-instance.edu/api/login',
    data=login_data
)

if login_response.ok:
    # Make authenticated requests using the same session
    announcements = session.get(
        'https://your-sakai-instance.edu/api/users/me/announcements'
    )
    print(announcements.json())

​
Logout

​
POST /api/logout
endpoint
Terminate the current session

​
Request

curl -X POST https://your-sakai-instance.edu/api/logout \
  -b cookies.txt

​
Response

{
  "status": "success",
  "message": "Logged out successfully"
}
Always call the logout endpoint when your application is done to free server resources.

​
Security Best Practices

​
HTTPS Required

Always use HTTPS in production to protect credentials and session cookies from interception.

​
Secure Cookies

Configure secure cookies in production: 
# In sakai.properties
cookie.secure=true
cookie.httponly=true
cookie.samesite=strict

​
CSRF Protection

The REST API includes CSRF protection for state-changing operations. For POST, PUT, and DELETE requests, you may need to include a CSRF token.

​
Session Fixation Prevention

Sakai regenerates session IDs after successful authentication to prevent session fixation attacks.

​
Error Handling

​
Common Authentication Errors

The username or password is incorrect. Verify credentials and try again.
The session cookie is missing or expired. Re-authenticate via /api/login.
The authenticated user doesn’t have permission to access the requested resource.
If a session times out, you’ll receive a 401 error. Implement automatic re-authentication or prompt the user to log in again.

​
Next Steps

API Endpoints

Explore available REST API endpoints

Examples

View complete REST API usage examples

Build docs developers (and LLMs) love

Get started for freeTalk to us