# MCIAS API Documentation

## Overview

MCIAS (Metacircular Identity and Access System) provides identity and authentication services across metacircular projects. This document describes the REST API endpoints, request/response formats, and error handling.

## API Endpoints

### Authentication

#### Password-based Authentication

**Endpoint**: `POST /v1/login/password`

**Description**: Authenticates a user using username and password credentials. This endpoint does not require TOTP verification, even if TOTP is enabled for the user.

**Request Format**:
```json
{
    "version": "v1",
    "login": {
        "user": "username",
        "password": "secret_password"
    }
}
```

**Required Fields**:
- `version`: Must be "v1"
- `login.user`: Username
- `login.password`: User's password

**Response Format** (Success - 200 OK):
```json
{
    "token": "authentication_token",
    "expires": 1621234567,
    "totp_enabled": true
}
```

**Response Fields**:
- `token`: Authentication token to be used for subsequent requests
- `expires`: Unix timestamp when the token expires
- `totp_enabled`: Boolean indicating whether TOTP is enabled for the user

**Error Responses**:
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Invalid username or password
- 500 Internal Server Error: Server-side error

#### Token-based Authentication

**Endpoint**: `POST /v1/login/token`

**Description**: Authenticates a user using a previously issued token.

**Request Format**:
```json
{
    "version": "v1",
    "login": {
        "user": "username",
        "token": "existing_token"
    }
}
```

**Required Fields**:
- `version`: Must be "v1"
- `login.user`: Username
- `login.token`: Previously issued authentication token

**Response Format** (Success - 200 OK):
```json
{
    "token": "new_authentication_token",
    "expires": 1621234567
}
```

**Response Fields**:
- `token`: New authentication token to be used for subsequent requests
- `expires`: Unix timestamp when the token expires

**Error Responses**:
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Invalid or expired token
- 500 Internal Server Error: Server-side error

#### TOTP Verification

**Endpoint**: `POST /v1/login/totp`

**Description**: Verifies a TOTP code for a user and issues a token upon successful verification. This endpoint is used as a separate flow from password authentication.

**Request Format**:
```json
{
    "version": "v1",
    "username": "username",
    "totp_code": "123456"
}
```

**Required Fields**:
- `version`: Must be "v1"
- `username`: Username
- `totp_code`: Time-based One-Time Password code

**Response Format** (Success - 200 OK):
```json
{
    "token": "authentication_token",
    "expires": 1621234567
}
```

**Response Fields**:
- `token`: Authentication token to be used for subsequent requests
- `expires`: Unix timestamp when the token expires

**Error Responses**:
- 400 Bad Request: Invalid request format, missing required fields, or TOTP not enabled for user
- 401 Unauthorized: Invalid TOTP code
- 500 Internal Server Error: Server-side error

### Database Credentials

**Endpoint**: `/v1/credentials/database` (Not yet implemented)

**Description**: Retrieves database credentials for authorized users.

## Error Handling

All error responses follow a standard format:

```json
{
    "error": "Error message describing the issue"
}
```

Common HTTP status codes:
- 200 OK: Request successful
- 400 Bad Request: Invalid request format or parameters
- 401 Unauthorized: Authentication failed
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource not found
- 500 Internal Server Error: Server-side error

## Authentication Flow

### Password Authentication Flow

1. **Initial Authentication**:
   - Client sends username and password to `/v1/login/password`
   - Server validates credentials and returns a token
   - The response includes a `totp_enabled` flag indicating whether TOTP is enabled for the user

2. **Subsequent Requests**:
   - Client uses the token for authentication by sending it to `/v1/login/token`
   - Server validates the token and issues a new token

### TOTP Authentication Flow

1. **TOTP Verification** (separate from password authentication):
   - Client sends username and TOTP code to `/v1/login/totp`
   - Server validates the TOTP code and returns a token if valid

### Token Management

1. **Token Expiration**:
   - Tokens expire after 24 hours
   - Clients should request a new token before expiration

### Multi-Factor Authentication

For users with TOTP enabled, a complete multi-factor authentication flow would involve:
1. Authenticate with username and password using `/v1/login/password`
2. Check the `totp_enabled` flag in the response
3. If TOTP is enabled, prompt the user for their TOTP code
4. Verify the TOTP code using `/v1/login/totp` to get a second token
5. Use either token for subsequent requests (both are valid)