sso

docs/api_reference.md

@@ -0,0 +1,140 @@
+# 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**:
+```json
+{
+  "username": "jdoe",
+  "password": "secretpassword",
+  "api_key": "YOUR_APP_API_KEY"
+}
+```
+
+**Response (Success - 200 OK)**:
+```json
+{
+  "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`.*
+```json
+{
+  "authorized": false,
+  "message": "Invalid username or password" 
+  // OR "User not authorized for this application"
+  // OR "User account is inactive"
+}
+```
+
+**Example Usage (cURL)**:
+```bash
+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**:
+```json
+{
+  "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**:
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "password123",
+  "is_admin": false
+}
+```
+
+### `PUT /users/{user_id}`
+**Description**: Update a user.
+**Body**:
+```json
+{
+  "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**:
+```json
+{
+  "name": "OpenProject",
+  "url": "https://openproject.nabd-co.com"
+}
+```
+**Response**:
+Returns the created app object, including the **`api_key`**.