Skip to main content

​
Phase 1.4 Deliverable E: Authentication & Endpoint Readiness

​
Admin Endpoints

​
PEPM Agent Map Endpoints

Create PEPM Mapping:
  • Path: POST /api/v1/admin/identity/pepm-map
  • RBAC: Admin/CEO only (enforced via require_admin_or_ceo dependency)
  • Request Schema: PEPMAgentMapCreate (from api/schemas/admin_identity.py:30-41)
Request Payload: 
{
  "pepm_agent_name_norm": "KENNY YOUNG",
  "pepm_business_name_norm": "ACME INC",
  "agent_key": "AGENT:CAFEBABECAFEBABE",
  "resolved_agent_id": null,
  "match_source": "initial_mapping",
  "effective_start_date": "2024-01-01",
  "effective_end_date": null,
  "is_active": true,
  "reason": "Initial Phase 1.3 production mapping - derived from Stage3 snapshots",
  "notes": null
}
Response Schema: PEPMAgentMapResponse (includes override_id, created_at, created_by, etc.) Update PEPM Mapping (closure only):
  • Path: PUT /api/v1/admin/identity/pepm-map
  • Request Schema: PEPMAgentMapUpdate (requires override_id, allows effective_end_date, is_active, notes)

​
Agent Identity Admin Endpoints

Create Agent Identity Override:
  • Path: POST /api/v1/admin/identity/agent
  • RBAC: Admin/CEO only
  • Request Schema: AgentIdentityAdminCreate
Update Agent Identity Override (closure only):
  • Path: PUT /api/v1/admin/identity/agent
  • Request Schema: AgentIdentityAdminUpdate (requires override_id)

​
Authentication

Token Acquisition:
  • Endpoint: POST /api/v1/auth/token
  • Location: api/routes/auth.py
Token Requirements:
  • User must have role = "admin" or "ceo" in JWT payload
  • Token must include tenant_id matching target tenant
  • Token subject (sub) must exist in dim_users table (if BigQuery enrichment enabled)
Token Usage:
  • Include in request header: Authorization: Bearer <JWT_TOKEN>
  • Token is validated via get_current_user dependency
  • RBAC check happens in require_admin_or_ceo function

​
File References

  • Endpoints: api/routes/admin_identity.py:179-222 (PEPM map), api/routes/admin_identity.py:49-91 (agent identity)
  • Schemas: api/schemas/admin_identity.py:30-41 (PEPMAgentMapCreate), api/schemas/admin_identity.py:9-19 (AgentIdentityAdminCreate)
  • Auth: api/routes/auth.py (token endpoint)
  • Dependencies: api/dependencies.py (get_current_user, get_tenant_id)
  • RBAC: api/routes/admin_identity.py:33-42 (require_admin_or_ceo)