ibexharness
DocsBlogReleasesRoadmap
GitHub
ibexharness

Documentation

Security overviewAuthenticationTenant isolationSecrets and keys
Security›Authentication
Security

Authentication

Token types, proxy auth pipeline, and fail-closed behavior in Phase 1.

Every protected proxy request passes through token validation and agent identity verification before the handler runs. The proxy delegates to the auth service over gRPC — it never stores token hashes locally. For service responsibilities and token issuance, see the Auth service docs.

Fail closed

Auth or agent verification failures deny the request. There is no anonymous fallback on protected routes. Auth gRPC outage returns 503 AUTH_UNAVAILABLE, not passthrough.

Token types

IBEX Harness supports several token classes. Each has a different risk profile and rotation policy.

TypeLifetimeTypical useStorage
Personal Access Token (PAT)Until revokedSDK and server integrationsArgon2id hash in Postgres
Organization tokenRotatableProduction agentsSame as PAT
Dashboard session (JWT)~1 hourOperator UI (Phase 2+)RS256 signed; refresh rotation
Service token~24 hoursInternal service-to-serviceNarrow scopes; auto-rotation
Marketplace tokenScopedPublish/install resources (Phase 3+)Narrow scope only

Phase 1 focus

Phase 1 implements PAT validation via gRPC ValidateToken and ValidateAgent. Dashboard JWT and OIDC flows are documented for completeness; full dashboard auth ships later.

Proxy middleware order

Protected routes run middleware in this order:

Mermaid diagram: graph LR
+---------+     +---------------------+          +----------------------+      +------------+      +---------+
|         |     |                     |          |                      |      |            |      |         |
| Request |---->| Auth: ValidateToken |   ------>| Agent: ValidateAgent |----->| Rate limit |----->| Handler |
|         |     |                     |          |                      |      |            |      |         |
+---------+     +---------------------+          +----------------------+      +------------+      +---------+
                           |                                 |                        |                       
                           |                                 |                        |                       
                           |                                 +--------------+         +---------+             
                           |                                                |                   |             
                           |                                                |                   |             
                           |                     +----------------------+   |  +------------+   |  +---------+
                           |                     |                      |   |  |            |   |  |         |
                           +--------fail-------->|      401 / 503       |  fail|    403     |  deny|   429   |
                                                 |                      |      |            |      |         |
                                                 +----------------------+      +------------+      +---------+
1

Token validation

gRPC ValidateToken resolves org_id and permission bitmap from the bearer token. Invalid, expired, or revoked tokens return 401.

2

Agent identity

gRPC ValidateAgent(agent_id, org_id_from_token) requires header X-IBEX-Agent-ID. Cross-org or inactive agents return 403 (AGENT_NOT_AUTHORIZED), never 404.

3

Rate limit

Org-level RPM via Redis. Redis errors fail open per ADR-0015.

Required headers

ParameterTypeDescription
AuthorizationRequiredstring
Bearer token — PAT issued by auth service CreateToken.
X-IBEX-Agent-IDRequireduuid
Calling agent UUID; must belong to the org in the URL path.
Content-TypeRequiredstring
application/json on POST bodies with a JSON payload.

Probe a protected route

bash
curl -s -w "\nHTTP %{http_code}\n" \
  -X POST "http://localhost:8080/v1/orgs/${IBEX_DEV_ORG_ID}/chat/completions" \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'

Phase 1 expected: 501 PROVIDER_NOT_CONFIGURED — auth and agent checks passed; provider forwarding is deferred.

Error responses

HTTPCodeMeaning
401MISSING_TOKEN, INVALID_TOKENNo bearer or token not valid
403AGENT_NOT_AUTHORIZED, INSUFFICIENT_PERMISSIONSAgent wrong org or missing permission bit
503AUTH_UNAVAILABLE, SERVICE_DEGRADEDAuth gRPC unreachable or degraded

All errors use the stable JSON envelope documented in Errors.

Authorization model

Permissions use a 64-bit bitmap (ADR-0009). Phase 1 proxy chat minimum: MemoryRead | SessionCreate | SessionRead. Token create/revoke requires explicit TokenCreate / TokenRevoke bits.

Authentication ≠ authorization

A valid token does not imply access to every resource in the org. Endpoints declare required permissions; cross-tenant resource IDs return 403.

Local dev timeout

Argon2 verify on developer machines can exceed the production 50ms auth budget. If smoke tests return 503, increase the validate timeout:

bash
IBEX_AUTH_VALIDATE_TIMEOUT=2s go run ./services/proxy/cmd/proxy

See Troubleshooting for migration and compose-dev issues.

Related

  • Issuing API keys
  • Proxy authentication
  • ADR-0011: Proxy auth client
  • ADR-0016: Agent identity verification

Was this page helpful?

Edit on GitHub

Last updated on

PreviousSecurity overviewNextTenant isolation

On this page

  • Token types
  • Proxy middleware order
  • Required headers
  • Probe a protected route
  • Error responses
  • Authorization model
  • Local dev timeout
  • Related
0%