feat: limit auth deps to bearer token and ip allowlist

.env.example

@@ -26,8 +26,9 @@ GUARDRAILS_HUB_API_KEY="<ADD-KEY>"
 HF_TOKEN="<ADD-HF-KEY>"
 # SHA-256 hex digest of your bearer token (64 lowercase hex chars)
 AUTH_TOKEN="<ADD-HASH-TOKEN>"
-KAAPI_AUTH_URL="<ADD-KAAPI-AUTH-URL>"
-KAAPI_AUTH_TIMEOUT=5
+# Comma-separated source IPs allowed to call this service (kaapi-backend).
+# Empty disables the check; required when ENVIRONMENT=production.
+ALLOWED_IPS="127.0.0.1"
 
 # URL for the guardrails API — required for the multiple_validators evaluation script
 GUARDRAILS_API_URL="http://localhost:8001/api/v1/guardrails/"

.env.test.example

@@ -25,5 +25,6 @@ OPENAI_API_KEY="<ADD-KEY>"
 GUARDRAILS_HUB_API_KEY="<ADD-KEY>"
 # SHA-256 hex digest of your bearer token (64 lowercase hex chars)
 AUTH_TOKEN="<ADD-HASH-TOKEN>"
-KAAPI_AUTH_URL="<ADD-KAAPI-AUTH-URL>"
-KAAPI_AUTH_TIMEOUT=5
+# Comma-separated source IPs allowed to call this service (kaapi-backend).
+# Empty disables the check; required when ENVIRONMENT=production.
+ALLOWED_IPS="127.0.0.1"

backend/.guardrails/hub_registry.json

@@ -6,31 +6,31 @@
       "exports": [
         "BanList"
       ],
-      "installed_at": "2026-05-12T05:28:55.036165+00:00",
+      "installed_at": "2026-07-23T14:06:37.542360+00:00",
       "package_name": "guardrails-grhub-ban-list"
     },
     "guardrails/llm_critic": {
       "import_path": "guardrails_grhub_llm_critic",
       "exports": [
         "LLMCritic"
       ],
-      "installed_at": "2026-05-12T05:29:05.596003+00:00",
+      "installed_at": "2026-07-23T14:06:45.369592+00:00",
       "package_name": "guardrails-grhub-llm-critic"
     },
     "guardrails/llamaguard_7b": {
       "import_path": "guardrails_grhub_llamaguard_7b",
       "exports": [
         "LlamaGuard7B"
       ],
-      "installed_at": "2026-05-12T05:29:16.995441+00:00",
+      "installed_at": "2026-07-23T14:06:51.618169+00:00",
       "package_name": "guardrails-grhub-llamaguard-7b"
     },
     "guardrails/profanity_free": {
       "import_path": "guardrails_grhub_profanity_free",
       "exports": [
         "ProfanityFree"
       ],
-      "installed_at": "2026-05-12T05:29:28.079410+00:00",
+      "installed_at": "2026-07-23T14:07:02.770910+00:00",
       "package_name": "guardrails-grhub-profanity-free"
     },
     "guardrails/nsfw_text": {

backend/README.md

@@ -191,19 +191,32 @@ echo -n "your-plain-text-token" | shasum -a 256
 
 Set the resulting digest as `AUTH_TOKEN` in your `.env` / `.env.test`.
 
-## Multi-tenant API Key Configuration
+## Caller Authentication
 
-Ban List and LLM Prompt Config APIs use `X-API-KEY` auth instead of bearer token auth.
+kaapi-guardrails is an internal service. Its only caller is kaapi-backend, which authenticates the
+end user and resolves the tenant before calling.
 
-Required environment variables:
-- `KAAPI_AUTH_URL`: Base URL of the Kaapi auth service used to verify API keys.
-- `KAAPI_AUTH_TIMEOUT`: Timeout in seconds for auth verification calls.
+Every request (except the health check) must carry:
 
-At runtime, the backend calls:
-- `GET {KAAPI_AUTH_URL}/apikeys/verify`
-- Header: `X-API-KEY: <token>`
+- `Authorization: Bearer <plain-text-token>`
+- `X-ORGANIZATION-ID: <int>` and `X-PROJECT-ID: <int>` — the tenant, resolved by kaapi-backend
+- and originate from an IP listed in `ALLOWED_IPS`
 
-If verification succeeds, tenant's scope (`organization_id`, `project_id`) is resolved from the auth response and applied to tenant-scoped CRUD operations (for example Ban Lists and LLM Prompt Configs).
+`ALLOWED_IPS` is a comma-separated list of source IPs allowed to reach this service:
+
+```bash
+ALLOWED_IPS="10.0.3.14"
+```
+
+Leave it empty to disable the check for local development. It is required when
+`ENVIRONMENT=production` — the service will not start without it.
+
+Rejections:
+- Source IP not whitelisted → `403` (checked before the token)
+- Missing or invalid token → `401`
+- Missing or non-integer tenant headers → `422`
+
+Tenant scope is never read from the query string or request body.
 
 ## Guardrails AI Setup
 

backend/app/api/API_USAGE.md

@@ -18,14 +18,16 @@ Example local base URL:
 
 ## Authentication
 
-This API currently uses two auth modes:
+This service is internal. Its only caller is kaapi-backend, which authenticates the end user and
+resolves the tenant before calling.
 
-1. Bearer token auth (`Authorization: Bearer <plain-text-token>`)
-   - Used by validator config and guardrails endpoints.
-   - The server validates your plaintext bearer token against a SHA-256 digest stored in `AUTH_TOKEN`.
-2. multi-tenant API key auth (`X-API-KEY: <token>`)
-   - Used by ban list and LLM prompt config endpoints.
-   - The API key is verified against `KAAPI_AUTH_URL` and resolves tenant's scope (`organization_id`, `project_id`).
+Every request must carry:
+
+- `Authorization: Bearer <plain-text-token>` — validated against the SHA-256 digest in `AUTH_TOKEN`
+- `X-ORGANIZATION-ID: <int>` and `X-PROJECT-ID: <int>` — the tenant, resolved by kaapi-backend
+- and must arrive from an IP listed in `ALLOWED_IPS`
+
+Tenant scope is never read from the query string or request body.
 
 Notes:
 - `GET /utils/health-check/` is public.
@@ -74,13 +76,15 @@ Base path:
 ## 2.1 Create validator config
 
 Endpoint:
-- `POST /api/v1/guardrails/validators/configs/?organization_id=1&project_id=101`
+- `POST /api/v1/guardrails/validators/configs/`
 
 Example (PII input validator):
 
 ```bash
-curl -X POST "http://localhost:8001/api/v1/guardrails/validators/configs/?organization_id=1&project_id=101" \
+curl -X POST "http://localhost:8001/api/v1/guardrails/validators/configs/" \
   -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "type": "pii_remover",
@@ -95,7 +99,7 @@ curl -X POST "http://localhost:8001/api/v1/guardrails/validators/configs/?organi
 ## 2.2 List validator configs
 
 Endpoint:
-- `GET /api/v1/guardrails/validators/configs/?organization_id=1&project_id=101`
+- `GET /api/v1/guardrails/validators/configs/`
 
 Optional filters:
 - `ids=<uuid>&ids=<uuid>`
@@ -106,32 +110,38 @@ Optional filters:
 Example:
 
 ```bash
-curl -X GET "http://localhost:8001/api/v1/guardrails/validators/configs/?organization_id=1&project_id=101&stage=input" \
-  -H "Authorization: Bearer <token>"
+curl -X GET "http://localhost:8001/api/v1/guardrails/validators/configs/?stage=input" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 2.3 Get validator config by id
 
 Endpoint:
-- `GET /api/v1/guardrails/validators/configs/{id}?organization_id=1&project_id=101`
+- `GET /api/v1/guardrails/validators/configs/{id}`
 
 Example:
 
 ```bash
-curl -X GET "http://localhost:8001/api/v1/guardrails/validators/configs/<validator_id>?organization_id=1&project_id=101" \
-  -H "Authorization: Bearer <token>"
+curl -X GET "http://localhost:8001/api/v1/guardrails/validators/configs/<validator_id>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 2.4 Update validator config
 
 Endpoint:
-- `PATCH /api/v1/guardrails/validators/configs/{id}?organization_id=1&project_id=101`
+- `PATCH /api/v1/guardrails/validators/configs/{id}`
 
 Example:
 
 ```bash
-curl -X PATCH "http://localhost:8001/api/v1/guardrails/validators/configs/<validator_id>?organization_id=1&project_id=101" \
+curl -X PATCH "http://localhost:8001/api/v1/guardrails/validators/configs/<validator_id>" \
   -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "is_enabled": false,
@@ -142,13 +152,15 @@ curl -X PATCH "http://localhost:8001/api/v1/guardrails/validators/configs/<valid
 ## 2.5 Delete validator config
 
 Endpoint:
-- `DELETE /api/v1/guardrails/validators/configs/{id}?organization_id=1&project_id=101`
+- `DELETE /api/v1/guardrails/validators/configs/{id}`
 
 Example:
 
 ```bash
-curl -X DELETE "http://localhost:8001/api/v1/guardrails/validators/configs/<validator_id>?organization_id=1&project_id=101" \
-  -H "Authorization: Bearer <token>"
+curl -X DELETE "http://localhost:8001/api/v1/guardrails/validators/configs/<validator_id>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 3) Runtime Validator Discovery
@@ -163,7 +175,9 @@ Example:
 
 ```bash
 curl -X GET "http://localhost:8001/api/v1/guardrails/" \
-  -H "Authorization: Bearer <token>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 4) Guardrail Execution
@@ -192,11 +206,11 @@ Example:
 ```bash
 curl -X POST "http://localhost:8001/api/v1/guardrails/?suppress_pass_logs=true" \
   -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "request_id": "2a6f6d5c-5b9f-4f6b-92e4-cf7d67f87932",
-    "organization_id": 1,
-    "project_id": 101,
     "input": "Amit Gupta phone number is 919611188278",
     "validators": [
       {
@@ -264,7 +278,7 @@ Possible failure response:
 
 ## 5) Ban List APIs (multi-tenant)
 
-These endpoints manage tenant-scoped ban lists and use `X-API-KEY` auth.
+These endpoints manage tenant-scoped ban lists. The tenant comes from the `X-ORGANIZATION-ID` / `X-PROJECT-ID` headers.
 
 Base path:
 - `/api/v1/guardrails/ban_lists`
@@ -278,7 +292,9 @@ Example:
 
 ```bash
 curl -X POST "http://localhost:8001/api/v1/guardrails/ban_lists/" \
-  -H "X-API-KEY: <api-key>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "Safety Banned Terms",
@@ -298,7 +314,9 @@ Example:
 
 ```bash
 curl -X GET "http://localhost:8001/api/v1/guardrails/ban_lists/?offset=0&limit=20" \
-  -H "X-API-KEY: <api-key>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 5.3 Get ban list by id
@@ -310,7 +328,9 @@ Example:
 
 ```bash
 curl -X GET "http://localhost:8001/api/v1/guardrails/ban_lists/<ban_list_id>" \
-  -H "X-API-KEY: <api-key>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 5.4 Update ban list
@@ -322,7 +342,9 @@ Example:
 
 ```bash
 curl -X PATCH "http://localhost:8001/api/v1/guardrails/ban_lists/<ban_list_id>" \
-  -H "X-API-KEY: <api-key>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "description": "Updated description",
@@ -339,12 +361,14 @@ Example:
 
 ```bash
 curl -X DELETE "http://localhost:8001/api/v1/guardrails/ban_lists/<ban_list_id>" \
-  -H "X-API-KEY: <api-key>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 6) LLM Prompt Config APIs (multi-tenant)
 
-These endpoints manage tenant-scoped LLM prompt configs for the `topic_relevance` and `answer_relevance_custom_llm` validators. They use `X-API-KEY` auth.
+These endpoints manage tenant-scoped LLM prompt configs for the `topic_relevance` and `answer_relevance_custom_llm` validators. The tenant comes from the `X-ORGANIZATION-ID` / `X-PROJECT-ID` headers.
 
 Base path:
 - `/api/v1/guardrails/llm_prompt_configs`
@@ -362,7 +386,9 @@ Example (topic relevance):
 
 ```bash
 curl -X POST "http://localhost:8001/api/v1/guardrails/llm_prompt_configs/" \
-  -H "X-API-KEY: <api-key>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "validator_name": "topic_relevance",
@@ -377,7 +403,9 @@ Example (answer relevance):
 
 ```bash
 curl -X POST "http://localhost:8001/api/v1/guardrails/llm_prompt_configs/" \
-  -H "X-API-KEY: <api-key>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "validator_name": "answer_relevance_custom_llm",
@@ -399,7 +427,9 @@ Example:
 
 ```bash
 curl -X GET "http://localhost:8001/api/v1/guardrails/llm_prompt_configs/?validator_name=topic_relevance&offset=0&limit=20" \
-  -H "X-API-KEY: <api-key>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 6.3 Get LLM prompt config by id
@@ -411,7 +441,9 @@ Example:
 
 ```bash
 curl -X GET "http://localhost:8001/api/v1/guardrails/llm_prompt_configs/<config_id>" \
-  -H "X-API-KEY: <api-key>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 6.4 Update LLM prompt config
@@ -423,7 +455,9 @@ Example:
 
 ```bash
 curl -X PATCH "http://localhost:8001/api/v1/guardrails/llm_prompt_configs/<config_id>" \
-  -H "X-API-KEY: <api-key>" \
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101" \
   -H "Content-Type: application/json" \
   -d '{
     "llm_prompt": "Pregnancy care: Updated scope definition"
@@ -439,7 +473,9 @@ Example:
 
 ```bash
 curl -X DELETE "http://localhost:8001/api/v1/guardrails/llm_prompt_configs/<config_id>" \
-  -H "X-API-KEY: <api-key>"
+  -H "Authorization: Bearer <token>" \
+  -H "X-ORGANIZATION-ID: 1" \
+  -H "X-PROJECT-ID: 101"
 ```
 
 ## 8) End-to-End Usage Pattern
@@ -460,10 +496,10 @@ Recommended request flow:
   - Add `Authorization: Bearer <token>`.
 - `401 Invalid authorization token`
   - Verify plaintext token matches server-side hash.
-- `401 Missing X-API-KEY header`
-  - Add `X-API-KEY: <api-key>` for ban list and LLM prompt config endpoints.
-- `401 Invalid API key`
-  - Verify the API key is valid in the upstream Kaapi auth service.
+- `403 Forbidden`
+  - Source IP is not in `ALLOWED_IPS`. Checked before the token.
+- `422` on tenant headers
+  - Add `X-ORGANIZATION-ID` and `X-PROJECT-ID`; both must be integers.
 - `Invalid request_id`
   - Ensure `request_id` is a valid UUID string.
 - `Validator already exists for this type and stage`