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