185 lines
4.9 KiB
Markdown
185 lines
4.9 KiB
Markdown
# 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)
|