auth-proxy/docs/api.md

Auth-gate 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

List all currently active temporary whitelisted IPs.

Authorization: Bearer {API_TOKEN}

Response body:

[
  {
    "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:

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.