# 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`**.