Auth: helvia-rag-pipelines
How this service handles authentication. Full flows:
docs/architecture/auth-flows.md
Tokens This Service Accepts
| Token type | Where validated | Guard / middleware |
|---|---|---|
| Pipeline JWT (Bearer) | Validated locally by JWTBearer class (extends HTTPBearer). HS256 with JWT_SECRET env var. | FastAPI dependency injection on protected routes |
Public endpoints (no token required): GET / (root info endpoint).
Tokens This Service Sends
This service does not send JWTs to other services. It uses external API keys for third-party integrations:
| Calling | Token used | How attached |
|---|---|---|
| OpenAI | OpenAI API key | Authorization: Bearer <key> header |
| Azure OpenAI | Azure API key | api-key header |
| SemCache | SemCache token | Authorization: Bearer <token> header |
| RAG service | RAG user email | Custom header |
Tokens This Service Issues
| Token | Lifetime | Purpose |
|---|---|---|
| Pipeline JWT | No expiry by default | Access to pipeline endpoints. Payload: { role, pipeline_id, iat }. Issued via POST /admin/token (admin only). |
Roles / Scopes Enforced
Two roles: admin and client.
| Endpoint pattern | Required role |
|---|---|
POST /pipelines | admin |
GET /pipelines | admin |
GET /pipelines/{pipeline_id} | admin or client (pipeline_id must match token) |
PATCH /pipelines/{pipeline_id} | admin or client (pipeline_id must match token) |
DELETE /pipelines/{pipeline_id} | admin or client (pipeline_id must match token) |
PUT /pipelines/{pipeline_id}/corpus | admin or client (pipeline_id must match token) |
GET /pipelines/{pipeline_id}/corpus | admin or client (pipeline_id must match token) |
POST /pipelines/{pipeline_id}:process | admin or client (pipeline_id must match token) |
POST /pipelines/{pipeline_id}:search | admin or client (pipeline_id must match token) |
POST /pipelines/{pipeline_id}:train | admin or client (pipeline_id must match token) |
POST /pipelines/{pipeline_id}:index | admin or client (pipeline_id must match token) |
POST /admin/token | admin |
| Admin NLP providers | admin |
| Admin config endpoints | admin |
Client scope restriction: A client token contains a pipeline_id claim. The service verifies that the pipeline_id in the URL path matches the token's pipeline_id. This prevents clients from accessing pipelines they were not granted access to.
Admin bypass: The admin role has unrestricted access to all endpoints, regardless of pipeline_id.
Auth Notes
- This service has a completely independent auth system from hbf-core. It does not share secrets, tokens, or user databases with the rest of the platform.
- Tokens have no expiry by default. Rotation or revocation must be handled manually.
- All auth errors return HTTP 403 (not 401).
- The default
JWT_SECRETis"secret", which is insecure for production. Must be overridden via environment variable.