# 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

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/{ip}

Remove a temporary whitelisted IP.

**Authorization:** Bearer `{API_TOKEN}`

**Response:** 204 No Content

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

## Auth endpoint

The `/auth` endpoint uses HTTP Basic Auth for the fallback.

**Example:**

```bash
curl -u user:pass http://127.0.0.1:8080/auth
```

## 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 Basic Auth credentials are set via environment variables. Use strong passwords.