API Reference

Base URL & Security

https://your-cas-server.com/api

Generate an SSO token for a user. This is a server-to-server call using client credentials and a username. The endpoint is protected by IP whitelisting.

Request Body

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "username": "john_doe"
}

Success Response 200

{
  "redirect_url": "https://your-app.com/cas/callback?token=eyJhbG...",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Error Responses

// 401 — Invalid client credentials
{ "error": "Invalid client credentials" }

// 404 — User not found
{ "error": "User not found or inactive" }

Validate an SSO token and retrieve user information. Tokens are single-use — once validated, they cannot be reused.

Request Body

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Response 200

{
  "valid": true,
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "[email protected]"
  },
  "expires_at": "2026-03-10 22:30:00"
}

Initiate browser-based SSO login. Redirect users to this URL to authenticate via the CAS login page. After login, users are redirected to your callback URL with a token.

Query Parameters

Callback

// After successful login, user is redirected to:
https://your-app.com/cas/callback?token=eyJhbGciOiJIUzI1NiIs...

// Your callback should validate the token via POST /api/sso/validate

Retrieve the currently authenticated user's profile (session-based).

Response 200

{
  "id": 1,
  "username": "john_doe",
  "email": "[email protected]",
  "role": "user",
  "full_name": "John Doe"
}

Authenticate a user via the API. Returns user data on success.

Request Body

{
  "login": "john_doe",
  "password": "your_password"
}

Success Response 200

{
  "success": true,
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "[email protected]",
    "role": "user",
    "full_name": "John Doe"
  }
}

Error Responses

// 401 — Invalid credentials
{ "error": "Invalid credentials" }

// 423 — Account locked (too many failed attempts)
{ "error": "Account locked", "remaining_minutes": 25 }

// 429 — Rate limited
{ "error": "Too many attempts", "retry_after": 45 }

HTTP Status Codes