Concepts

IBEX Harness separates who is calling (organization + agent), what they may do (permissions), and where requests go (proxy routing). Understanding these three axes is enough to integrate against Phase 1 — memory, context assembly, and provider forwarding build on the same identity model later.

Platform vocabulary

Term	Meaning	Phase 1
Organization	Top-level tenant; owns agents, tokens, rate limits	Active — glossary
Agent	Autonomous actor inside an org; identified per request	Active
PAT	Personal Access Token — `ibex_pat_*` bearer credential	Active
RLS	Postgres row-level security isolating tenant rows	Active
Proxy	HTTP edge — auth, validate, rate limit, (future) forward	Active (no forward)
Memory	Persistent agent knowledge store	Not shipped
Directive	Behavioral instructions injected into LLM context	Not shipped

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; Argon2id verifies the secret server-side. Permissions are a 64-bit bitmap (ADR-0009).

User

Human operator linked to org membership. Phase 1 uses users for token audit trails; dashboard login is future work.

Entity relationships: Org and project model and Data model.

Request path (Phase 1)

+--------+                                     +-------+                            +------+    +-------+   
| Client |                                     | Proxy |                            | Auth |    | Redis |   
+--------+                                     +-------+                            +------+    +-------+   
     |                                             |                                    |           |       
     |  Bearer PAT + X-IBEX-Agent-ID + JSON body   |                                    |           |       
     |--------------------------------------------->                                    |           |       
     |                                             |                                    |           |       
     |                                             |           ValidateToken            |           |       
     |                                             |------------------------------------>           |       
     |                                             |                                    |           |       
     |                                             |        org_id, permissions         |           |       
     |                                             <....................................|           |       
     |                                             |                                    |           |       
     |                                             |  ValidateAgent(org_id, agent_id)   |           |       
     |                                             |------------------------------------>           |       
     |                                             |                                    |           |       
     |                                             |            authorized              |           |       
     |                                             <....................................|           |       
     |                                             |                                    |           |       
     |                                             |               rate limit check     |           |       
     |                                             |------------------------------------------------>       
     |                                             |                                    |           |       
     |                                             |               allowed / denied     |           |       
     |                                             <................................................|       
     |                                             |                                    |           |       
     |    501 PROVIDER_NOT_CONFIGURED (Phase 1)    |                                    |           |       
     <.............................................|                                    |           |       
     |                                             |                                    |           |       
+--------+                                     +-------+                            +------+    +-------+   
| Client |                                     | Proxy |                            | Auth |    | Redis |   
+--------+                                     +-------+                            +------+    +-------+

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

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"}]}'

Phase 1 expected response: HTTP 501 with PROVIDER_NOT_CONFIGURED — auth, agent verify, rate limit, and validation succeeded.

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 namespacing

Keys include org_id as the second segment — ratelimit:{org_id}:...

Details: Tenant isolation and Multi-tenant RLS.

Future concepts (not yet available)

The architecture doc describes services that do not run in Phase 1:

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       |---->|  Postgres |
| (PAT + Agent) |     |       |               |                  |     | SQL + RLS |
|               |     |       |               |                  |     |           |
+---------------+     +-------+               +------------------+     +-----------+
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                   +------------------+                  
                          :                   |                  |                  
                          :                   |                  |                  
                          +------------------>|      Redis       |                  
                          :                   |   rate limits    |                  
                          :                   |                  |                  
                          :                   +------------------+                  
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                   +------------------+                  
                          :                   |                  |                  
                          +......Phase.2.....>|   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	Phase 1
Organization	Top-level tenant; owns agents, tokens, rate limits	Active — glossary
Agent	Autonomous actor inside an org; identified per request	Active
PAT	Personal Access Token — `ibex_pat_*` bearer credential	Active
RLS	Postgres row-level security isolating tenant rows	Active
Proxy	HTTP edge — auth, validate, rate limit, (future) forward	Active (no forward)
Memory	Persistent agent knowledge store	Not shipped
Directive	Behavioral instructions injected into LLM context	Not shipped

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; Argon2id verifies the secret server-side. Permissions are a 64-bit bitmap (ADR-0009).

User

Human operator linked to org membership. Phase 1 uses users for token audit trails; dashboard login is future work.

Entity relationships: Org and project model and Data model.

Request path (Phase 1)

+--------+                                     +-------+                            +------+    +-------+   
| Client |                                     | Proxy |                            | Auth |    | Redis |   
+--------+                                     +-------+                            +------+    +-------+   
     |                                             |                                    |           |       
     |  Bearer PAT + X-IBEX-Agent-ID + JSON body   |                                    |           |       
     |--------------------------------------------->                                    |           |       
     |                                             |                                    |           |       
     |                                             |           ValidateToken            |           |       
     |                                             |------------------------------------>           |       
     |                                             |                                    |           |       
     |                                             |        org_id, permissions         |           |       
     |                                             <....................................|           |       
     |                                             |                                    |           |       
     |                                             |  ValidateAgent(org_id, agent_id)   |           |       
     |                                             |------------------------------------>           |       
     |                                             |                                    |           |       
     |                                             |            authorized              |           |       
     |                                             <....................................|           |       
     |                                             |                                    |           |       
     |                                             |               rate limit check     |           |       
     |                                             |------------------------------------------------>       
     |                                             |                                    |           |       
     |                                             |               allowed / denied     |           |       
     |                                             <................................................|       
     |                                             |                                    |           |       
     |    501 PROVIDER_NOT_CONFIGURED (Phase 1)    |                                    |           |       
     <.............................................|                                    |           |       
     |                                             |                                    |           |       
+--------+                                     +-------+                            +------+    +-------+   
| Client |                                     | Proxy |                            | Auth |    | Redis |   
+--------+                                     +-------+                            +------+    +-------+

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

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"}]}'

Phase 1 expected response: HTTP 501 with PROVIDER_NOT_CONFIGURED — auth, agent verify, rate limit, and validation succeeded.

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 namespacing

Keys include org_id as the second segment — ratelimit:{org_id}:...

Details: Tenant isolation and Multi-tenant RLS.

Future concepts (not yet available)

The architecture doc describes services that do not run in Phase 1:

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       |---->|  Postgres |
| (PAT + Agent) |     |       |               |                  |     | SQL + RLS |
|               |     |       |               |                  |     |           |
+---------------+     +-------+               +------------------+     +-----------+
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                   +------------------+                  
                          :                   |                  |                  
                          :                   |                  |                  
                          +------------------>|      Redis       |                  
                          :                   |   rate limits    |                  
                          :                   |                  |                  
                          :                   +------------------+                  
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                                                         
                          :                   +------------------+                  
                          :                   |                  |                  
                          +......Phase.2.....>|   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?