31fc204ef2
Rename the `entry` field to `ip` throughout the whitelist API for clarity and consistency. This affects API request/response bodies, path parameters, OpenAPI spec, documentation, and database queries in the audit log endpoint.
201 lines
4.6 KiB
Markdown
201 lines
4.6 KiB
Markdown
# Auth-proxy API Reference
|
|
|
|
## Endpoints
|
|
|
|
### POST /api/whitelist/temp
|
|
|
|
Create a temporary whitelisted IP.
|
|
|
|
**Authorization:** Bearer `{API_TOKEN}`
|
|
|
|
**Request body:**
|
|
|
|
```json
|
|
{
|
|
"ip": "1.2.3.4",
|
|
"ttl_seconds": 300,
|
|
"reason": "my laptop"
|
|
}
|
|
```
|
|
|
|
**Response:** 204 No Content
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```json
|
|
[
|
|
{
|
|
"ip": "1.2.3.4",
|
|
"reason": "my laptop",
|
|
"expires": "2024-01-01T12:05:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```json
|
|
{
|
|
"ip": "1.2.3.4"
|
|
}
|
|
```
|
|
|
|
**Response:** 204 No Content
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8080/api/whitelist/perm \
|
|
-H "Authorization: Bearer CHANGE_ME" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"ip":"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:**
|
|
|
|
```json
|
|
[
|
|
{
|
|
"ip": "203.0.113.10"
|
|
}
|
|
]
|
|
```
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
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/{ip}
|
|
|
|
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:**
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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:**
|
|
|
|
```bash
|
|
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`
|
|
|
|
```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.
|