sso/docs/api_reference.md

ASF SSO API Reference

This document details the API endpoints available in the ASF SSO service.

Base URL

https://sso.nabd-co.com (or http://localhost:8001 for local dev)

---

1. SSO Verification (External Apps)

This is the primary endpoint used by external applications to authenticate users.

POST /verify

Description: Verifies a user's credentials and checks if they are authorized for the calling application.

Headers:

• Content-Type: application/json

Request Body:

{
  "username": "jdoe",
  "password": "secretpassword",
  "api_key": "YOUR_APP_API_KEY"
}

Response (Success - 200 OK):

{
  "authorized": true,
  "message": "Authorized",
  "user": {
    "username": "jdoe",
    "email": "jdoe@example.com",
    "is_active": true,
    "is_admin": false,
    "id": 5,
    "created_at": "2026-01-25T12:00:00",
    "updated_at": "2026-01-25T12:00:00"
  }
}

Response (Failure - 200 OK): Note: The API returns 200 OK even for auth failures, but with authorized: false.

{
  "authorized": false,
  "message": "Invalid username or password" 
  // OR "User not authorized for this application"
  // OR "User account is inactive"
}

Example Usage (cURL):

curl -X POST https://sso.nabd-co.com/verify \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123",
    "api_key": "abc123xyz"
  }'

---

2. Admin Authentication

These endpoints are for the Admin Dashboard.

POST /token

Description: Login as an administrator to get an access token.

Request Body (Form Data):

• username: admin
• password: admin_password

Response:

{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "token_type": "bearer"
}

---

3. User Management (Admin Only)

Requires Header: Authorization: Bearer <access_token>

GET /users/

Description: List all users.

POST /users/

Description: Create a new user. Body:

{
  "username": "newuser",
  "email": "user@example.com",
  "password": "password123",
  "is_admin": false
}

PUT /users/{user_id}

Description: Update a user. Body:

{
  "email": "newemail@example.com",
  "is_active": false
}

POST /users/{user_id}/assign/{app_id}

Description: Assign a user to an application.

---

4. Application Management (Admin Only)

Requires Header: Authorization: Bearer <access_token>

GET /apps/

Description: List all registered applications.

POST /apps/

Description: Register a new application. Body:

{
  "name": "OpenProject",
  "url": "https://openproject.nabd-co.com"
}

Response: Returns the created app object, including the api_key.