Authentication Overview
Casper uses session-based authentication with secure HTTP-only cookies. All API requests to protected endpoints must include a valid session cookie.
The Casper frontend handles authentication automatically. This guide is for developers building custom integrations.
Logging In
Send a POST request to the login endpoint with your credentials. On success, the server sets an HTTP-only session cookie.
- POST /api/auth/login with { "username": "...", "password": "..." }
- On success: 200 response with user profile, session cookie is set automatically
- On failure: 401 response with error message
Session Management
Sessions are valid for 24 hours by default and refresh automatically on activity. You can manage active sessions from the Security settings page.
- Sessions expire after 24 hours of inactivity
- Active sessions refresh on each authenticated request
- You can view and revoke sessions from Settings > Security
- Logging out invalidates the current session server-side
Error Handling
Authentication errors return standard HTTP status codes. Handle these in your integration to provide a good user experience.
Never store session tokens in localStorage or expose them to client-side JavaScript. Casper uses HTTP-only cookies to prevent XSS token theft.
- 401 Unauthorized -- session expired or invalid, redirect to login
- 403 Forbidden -- authenticated but lacking permission for the resource
- 429 Too Many Requests -- rate limit exceeded, back off and retry