Concepts

IBEX Harness separates who is calling (organization + agent), what they may do (permissions), and where requests go (proxy routing + provider mode). Understanding these axes is enough to integrate against the shipped auth + proxy surface.

Platform vocabulary

Term	Meaning	Status
Organization	Top-level tenant; owns agents, tokens, rate limits	Shipped — glossary
Agent	Autonomous actor inside an org; identified per request	Shipped
PAT	Personal Access Token — `ibex_pat_*` bearer credential	Shipped
RLS	Postgres row-level security isolating tenant rows	Shipped
Proxy	HTTP edge — auth, rate limit, inject, forward	Shipped
Directive	Org behavioral instructions injected into chat	Shipped — Directives
Session	Conversation lifecycle + checkpoints	Shipped — Sessions
Memory	Persistent agent knowledge store	Not shipped (Phase 3)

Core entities

Organization

Every token belongs to exactly one organization (org_id). Rate limits, RLS policies, and future billing boundaries scope per org. Table: ibex_core.organizations.

Agent

An agent is an autonomous actor inside an org. The proxy requires X-IBEX-Agent-ID on protected routes and validates it via auth gRPC ValidateAgent.

Token (PAT)

Clients authenticate with a Personal Access Token. The proxy calls ValidateToken (optionally via bloom+LRU cache); Argon2id verifies the secret server-side. Permissions are a 64-bit bitmap (ADR-0009).

User

Human operator linked to org membership. Used for token audit trails; dashboard login is future work.

Entity relationships: Org and project model and Data model.

Request path (today)

+--------+                                     +-------+                              +------+    +-------+    +-----+   
| Client |                                     | Proxy |                              | Auth |    | Redis |    | LLM |   
+--------+                                     +-------+                              +------+    +-------+    +-----+   
     |                                             |                                      |           |           |      
     |  Bearer PAT + X-IBEX-Agent-ID + JSON body   |                                      |           |           |      
     |--------------------------------------------->                                      |           |           |      
     |                                             |                                      |           |           |      
     |                                             |  ValidateToken (cache miss → gRPC)   |           |           |      
     |                                             |-------------------------------------->           |           |      
     |                                             |                                      |           |           |      
     |                                             |         org_id, permissions          |           |           |      
     |                                             <......................................|           |           |      
     |                                             |                                      |           |           |      
     |                                             |   ValidateAgent(org_id, agent_id)    |           |           |      
     |                                             |-------------------------------------->           |           |      
     |                                             |                                      |           |           |      
     |                                             |             authorized               |           |           |      
     |                                             <......................................|           |           |      
     |                                             |                                      |           |           |      
     |                                             |                rate limit check      |           |           |      
     |                                             |-------------------------------------------------->           |      
     |                                             |                                      |           |           |      
     |                                             |                allowed / denied      |           |           |      
     |                                             <..................................................|           |      
     |                                             |                                      |           |           |      
     |                                             +---+                                  |           |           |      
     |                                             |   | resolve directive + session      |           |           |      
     |                                             <---+                                  |           |           |      
     |                                             |                                      |           |           |      
     |                                             |                  mock stub or live forward       |           |      
     |                                             |-------------------------------------------------------------->      
     |                                             |                                      |           |           |      
     |                                             |                         completion   |           |           |      
     |                                             <..............................................................|      
     |                                             |                                      |           |           |      
     |      200 (+ async checkpoint / trace)       |                                      |           |           |      
     <.............................................|                                      |           |           |      
     |                                             |                                      |           |           |      
+--------+                                     +-------+                              +------+    +-------+    +-----+   
| Client |                                     | Proxy |                              | Auth |    | Redis |    | LLM |   
+--------+                                     +-------+                              +------+    +-------+    +-----+

Full lifecycle documentation: Request lifecycle.

Required headers

Protected proxy routes require:

Authorization: Bearer ibex_pat_<uuid>_<secret>
X-IBEX-Agent-ID: <agent-uuid>
Content-Type: application/json   # POST bodies only

Optional: Idempotency-Key on non-streaming chat when Redis is configured.

bash

curl -X POST http://localhost:8080/v1/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"}]}'

Default mock mode expected response: HTTP 200. Use IBEX_LLM_MODE=live plus OPENAI_API_KEY for real provider responses.

Provider modes

Mode	When	Result
`mock` (default)	Local/dev without a provider key	In-process stub → HTTP 200
`live`	`OPENAI_API_KEY` set	Forward to OpenAI-compatible `/chat/completions`

Mock is not allowed when IBEX_ENV=production. Unregistered models return 501 PROVIDER_NOT_CONFIGURED.

Permission model

Permissions are bitwise flags on the token. Integrators need at minimum:

Permission	Required for
`ProxyChatCompletion`	Chat completion endpoint
`TokenCreate`	Issuing new PATs via gRPC

Admin seed tokens include broader bits for local development. Production tokens should follow least privilege — Authentication.

Error envelope

All JSON errors share a stable shape:

JSON

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "request_id": "0192a3b4-c5d6-7890-abcd-ef1234567890"
  }
}

Semantic validation adds field_errors[]. Use request_id to correlate with proxy and auth logs. Reference: API errors.

Multi-tenancy principles

org_id from token

Never trust org_id from request body or unvalidated URL segments.

403 not 404

Cross-tenant access returns Forbidden — ambiguous to attackers.

Defense in depth

Middleware, gRPC, store WHERE clauses, and Postgres RLS all enforce isolation.

Redis + ClickHouse namespacing

Redis keys include org_id; every ClickHouse query must filter org_id explicitly.

Details: Tenant isolation and Multi-tenant RLS.

Future concepts (not yet available)

Context assembly — parallel directive + memory retrieval (40ms budget)
Memory service — vector search, dedup, conflict detection
Embedder — text-to-vector for semantic recall
Worker — async extraction, fingerprinting, drift detection

Treat these as design targets when reading Architecture overview — not integration endpoints.

Mental model summary

+---------------+     +-------+                  +---------------------+
|               |     |       |                  |                     |
|               |     |       |                  |                     |
|     Client    |---->| Proxy |      ---gRPC---->|         Auth        |
| (PAT + Agent) |     |       |                  |                     |
|               |     |       |                  |                     |
+---------------+     +-------+                  +---------------------+
                          :                                 |           
                          :                                 |           
                          :                                 |           
                          :                                 |           
                          :                                 v           
                          :                      +---------------------+
                          :                      |                     |
                          :                      |                     |
                          +--------------------->|       Postgres      |
                          :                      |      SQL + RLS      |
                          :                      |                     |
                          :                      +---------------------+
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                      +---------------------+
                          :                      |                     |
                          :                      |                     |
                          +--------------------->|        Redis        |
                          :                      | rate limits + cache |
                          :                      |                     |
                          :                      +---------------------+
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                      +---------------------+
                          :                      |                     |
                          +-----mock-/-live----->|     LLM provider    |
                          :                      |                     |
                          :                      +---------------------+
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                      +---------------------+
                          :                      |                     |
                          +......Phase.3+.......>|   Memory / Context  |
                                                 |                     |
                                                 +---------------------+

Introduction — what works today vs roadmap
Quickstart — five-minute local setup
Auth overview — gRPC surface
Proxy overview — middleware and endpoints
Glossary — term definitions

Was this page helpful?

Platform vocabulary

Term	Meaning	Status
Organization	Top-level tenant; owns agents, tokens, rate limits	Shipped — glossary
Agent	Autonomous actor inside an org; identified per request	Shipped
PAT	Personal Access Token — `ibex_pat_*` bearer credential	Shipped
RLS	Postgres row-level security isolating tenant rows	Shipped
Proxy	HTTP edge — auth, rate limit, inject, forward	Shipped
Directive	Org behavioral instructions injected into chat	Shipped — Directives
Session	Conversation lifecycle + checkpoints	Shipped — Sessions
Memory	Persistent agent knowledge store	Not shipped (Phase 3)

Core entities

Organization

Every token belongs to exactly one organization (org_id). Rate limits, RLS policies, and future billing boundaries scope per org. Table: ibex_core.organizations.

Agent

An agent is an autonomous actor inside an org. The proxy requires X-IBEX-Agent-ID on protected routes and validates it via auth gRPC ValidateAgent.

Token (PAT)

User

Human operator linked to org membership. Used for token audit trails; dashboard login is future work.

Entity relationships: Org and project model and Data model.

Request path (today)

+--------+                                     +-------+                              +------+    +-------+    +-----+   
| Client |                                     | Proxy |                              | Auth |    | Redis |    | LLM |   
+--------+                                     +-------+                              +------+    +-------+    +-----+   
     |                                             |                                      |           |           |      
     |  Bearer PAT + X-IBEX-Agent-ID + JSON body   |                                      |           |           |      
     |--------------------------------------------->                                      |           |           |      
     |                                             |                                      |           |           |      
     |                                             |  ValidateToken (cache miss → gRPC)   |           |           |      
     |                                             |-------------------------------------->           |           |      
     |                                             |                                      |           |           |      
     |                                             |         org_id, permissions          |           |           |      
     |                                             <......................................|           |           |      
     |                                             |                                      |           |           |      
     |                                             |   ValidateAgent(org_id, agent_id)    |           |           |      
     |                                             |-------------------------------------->           |           |      
     |                                             |                                      |           |           |      
     |                                             |             authorized               |           |           |      
     |                                             <......................................|           |           |      
     |                                             |                                      |           |           |      
     |                                             |                rate limit check      |           |           |      
     |                                             |-------------------------------------------------->           |      
     |                                             |                                      |           |           |      
     |                                             |                allowed / denied      |           |           |      
     |                                             <..................................................|           |      
     |                                             |                                      |           |           |      
     |                                             +---+                                  |           |           |      
     |                                             |   | resolve directive + session      |           |           |      
     |                                             <---+                                  |           |           |      
     |                                             |                                      |           |           |      
     |                                             |                  mock stub or live forward       |           |      
     |                                             |-------------------------------------------------------------->      
     |                                             |                                      |           |           |      
     |                                             |                         completion   |           |           |      
     |                                             <..............................................................|      
     |                                             |                                      |           |           |      
     |      200 (+ async checkpoint / trace)       |                                      |           |           |      
     <.............................................|                                      |           |           |      
     |                                             |                                      |           |           |      
+--------+                                     +-------+                              +------+    +-------+    +-----+   
| Client |                                     | Proxy |                              | Auth |    | Redis |    | LLM |   
+--------+                                     +-------+                              +------+    +-------+    +-----+

Full lifecycle documentation: Request lifecycle.

Required headers

Protected proxy routes require:

Authorization: Bearer ibex_pat_<uuid>_<secret>
X-IBEX-Agent-ID: <agent-uuid>
Content-Type: application/json   # POST bodies only

Optional: Idempotency-Key on non-streaming chat when Redis is configured.

bash

curl -X POST http://localhost:8080/v1/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"}]}'

Default mock mode expected response: HTTP 200. Use IBEX_LLM_MODE=live plus OPENAI_API_KEY for real provider responses.

Provider modes

Mode	When	Result
`mock` (default)	Local/dev without a provider key	In-process stub → HTTP 200
`live`	`OPENAI_API_KEY` set	Forward to OpenAI-compatible `/chat/completions`

Mock is not allowed when IBEX_ENV=production. Unregistered models return 501 PROVIDER_NOT_CONFIGURED.

Permission model

Permissions are bitwise flags on the token. Integrators need at minimum:

Permission	Required for
`ProxyChatCompletion`	Chat completion endpoint
`TokenCreate`	Issuing new PATs via gRPC

Admin seed tokens include broader bits for local development. Production tokens should follow least privilege — Authentication.

Error envelope

All JSON errors share a stable shape:

JSON

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "request_id": "0192a3b4-c5d6-7890-abcd-ef1234567890"
  }
}

Semantic validation adds field_errors[]. Use request_id to correlate with proxy and auth logs. Reference: API errors.

Multi-tenancy principles

org_id from token

Never trust org_id from request body or unvalidated URL segments.

403 not 404

Cross-tenant access returns Forbidden — ambiguous to attackers.

Defense in depth

Middleware, gRPC, store WHERE clauses, and Postgres RLS all enforce isolation.

Redis + ClickHouse namespacing

Redis keys include org_id; every ClickHouse query must filter org_id explicitly.

Details: Tenant isolation and Multi-tenant RLS.

Future concepts (not yet available)

Context assembly — parallel directive + memory retrieval (40ms budget)
Memory service — vector search, dedup, conflict detection
Embedder — text-to-vector for semantic recall
Worker — async extraction, fingerprinting, drift detection

Treat these as design targets when reading Architecture overview — not integration endpoints.

Mental model summary

+---------------+     +-------+                  +---------------------+
|               |     |       |                  |                     |
|               |     |       |                  |                     |
|     Client    |---->| Proxy |      ---gRPC---->|         Auth        |
| (PAT + Agent) |     |       |                  |                     |
|               |     |       |                  |                     |
+---------------+     +-------+                  +---------------------+
                          :                                 |           
                          :                                 |           
                          :                                 |           
                          :                                 |           
                          :                                 v           
                          :                      +---------------------+
                          :                      |                     |
                          :                      |                     |
                          +--------------------->|       Postgres      |
                          :                      |      SQL + RLS      |
                          :                      |                     |
                          :                      +---------------------+
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                      +---------------------+
                          :                      |                     |
                          :                      |                     |
                          +--------------------->|        Redis        |
                          :                      | rate limits + cache |
                          :                      |                     |
                          :                      +---------------------+
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                      +---------------------+
                          :                      |                     |
                          +-----mock-/-live----->|     LLM provider    |
                          :                      |                     |
                          :                      +---------------------+
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                                             
                          :                      +---------------------+
                          :                      |                     |
                          +......Phase.3+.......>|   Memory / Context  |
                                                 |                     |
                                                 +---------------------+

Introduction — what works today vs roadmap
Quickstart — five-minute local setup
Auth overview — gRPC surface
Proxy overview — middleware and endpoints
Glossary — term definitions

Was this page helpful?