# Auth-gate 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}`

**Response body:**

```json
[
  {
    "ip": "1.2.3.4",
    "reason": "my laptop",
    "expires": "2024-01-01T12:05:00Z"
  }
]
```

### 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
{
  "entry": "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 '{"entry":"203.0.113.10"}'
```

### 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}`

**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:** 200 (allow) or 401 (deny)

### GET /status

Health check.

**Response:** 200 `ok`

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