8d25bda386
Update project structure to use a src/ directory layout and improve documentation across multiple files. - Update README.md build command to use ./src - Add directory structure documentation - Update status endpoint to include DB health status - Add pagination support (limit/offset) to whitelist list endpoints - Document new query parameters with examples - Update deployment guide to mark API token as required - Add testing instructions - Clarify audit log rotation in design documentation
4.6 KiB
Auth-proxy API Reference
Endpoints
POST /api/whitelist/temp
Create a temporary whitelisted IP.
Authorization: Bearer {API_TOKEN}
Request body:
{
"ip": "1.2.3.4",
"ttl_seconds": 300,
"reason": "my laptop"
}
Response: 204 No Content
Example:
curl -X POST http://127.0.0.1:8080/api/whitelist/temp \
-H "Authorization: Bearer CHANGE_ME" \
-H "Content-Type: application/json" \
-d '{"ip":"203.0.113.10","ttl_seconds":300,"reason":"admin laptop"}'
GET /api/whitelist/temp/list
List all currently active temporary whitelisted IPs.
Authorization: Bearer {API_TOKEN}
Query parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
int | No | 200 | Number of entries to return (max 1000) |
offset |
int | No | 0 | Number of entries to skip |
Response body:
[
{
"ip": "1.2.3.4",
"reason": "my laptop",
"expires": "2024-01-01T12:05:00Z"
}
]
Example:
curl -X GET "http://127.0.0.1:8080/api/whitelist/temp/list?limit=50&offset=0" \
-H "Authorization: Bearer CHANGE_ME"
DELETE /api/whitelist/temp/{ip}
Remove a temporary whitelisted IP.
Authorization: Bearer {API_TOKEN}
Response: 204 No Content
POST /api/whitelist/perm
Add a permanent whitelisted IP or CIDR range.
Authorization: Bearer {API_TOKEN}
Request body:
{
"entry": "1.2.3.4"
}
Response: 204 No Content
Example:
curl -X POST http://127.0.0.1:8080/api/whitelist/perm \
-H "Authorization: Bearer CHANGE_ME" \
-H "Content-Type: application/json" \
-d '{"entry":"203.0.113.10"}'
GET /api/whitelist/perm/list
List all currently active permanent whitelisted IPs.
Authorization: Bearer {API_TOKEN}
Query parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit |
int | No | 200 | Number of entries to return (max 1000) |
offset |
int | No | 0 | Number of entries to skip |
Response body:
[
{
"entry": "203.0.113.10"
}
]
Example:
curl -X GET "http://127.0.0.1:8080/api/whitelist/perm/list?limit=50&offset=0" \
-H "Authorization: Bearer CHANGE_ME"
DELETE /api/whitelist/perm/{entry}
Remove a permanent whitelisted IP or CIDR range.
Authorization: Bearer {API_TOKEN}
Response: 204 No Content
GET /api/logs
Retrieve audit log entries.
Authorization: Bearer {API_TOKEN}
Query parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
action |
string | No | Filter by action type (add_temp, delete_temp, add_perm, etc.) |
|
ip |
string | No | Filter by IP address | |
limit |
int | No | 200 | Number of entries to return (max 1000) |
offset |
int | No | 0 | Number of entries to skip |
Response body:
[
{
"timestamp": "2024-01-01T12:00:00Z",
"action": "add_temp",
"ip": "1.2.3.4",
"reason": "admin laptop",
"ttl_seconds": 300,
"api_client_ip": "10.0.0.1"
}
]
Example:
curl -X GET http://127.0.0.1:8080/api/logs \
-H "Authorization: Bearer CHANGE_ME"
GET /auth
The NGINX auth_request endpoint. Do NOT call this directly.
Response: 204 No Content (allow) or 401 (deny)
GET /status
Health check with DB status.
Response: 200 application/json
{
"status": "ok",
"uptime": "1h30m0s",
"perm_whitelist_count": 15,
"temp_whitelist_count": 3,
"db_ok": true
}
Security notes
- The API is not exposed publicly. It's only accessible from NGINX via Docker internal networking.
- The API token is the only secret for the API. Keep it in the environment.
- The auth endpoint only checks IP whitelisting (no Basic Auth fallback).
- Always serve the auth endpoint over TLS.