Org and project model

IBEX Harness scopes all runtime identity to an organization. Agents belong to exactly one org; tokens are issued per org and encode a permission bitmap for that tenant. The proxy derives org_id from the validated PAT — never from request body fields.

Entity hierarchy

+--------------+      +------+         
| ORGANIZATION ||---o<| USER |         
+--------------+ has  +------+         
        |                 |            
    ------issues----------- may_create 
    |   |          |      |            
   o<   |         o<      |            
+-------+      +-------+               
| AGENT ||---o<| TOKEN |               
+-------+may_bi+-------+

Organization

Top-level tenant. Owns agents, tokens, and rate-limit buckets. Table: ibex_core.organizations.

User

Human operator (Phase 1 subset). Linked to org membership for token issuance audit. Table: ibex_core.users.

Agent

Autonomous actor that calls the proxy. Identified by X-IBEX-Agent-ID on every protected request. Table: ibex_core.agents.

Token

PAT credential with permission bitmap, bound to org (and optionally user/agent). Table: ibex_core.tokens.

Full schema reference: Data model.

Runtime binding rules

Rule	Enforcement
Token org is authoritative	Proxy middleware after `ValidateToken`
Agent must belong to token org	`ValidateAgent` gRPC + store WHERE clause
Path org must match token org	`/v1/orgs/{org_id}/auth-probe` only
Cross-tenant access	`403` — never `404`

Chat completions use POST /v1/chat/completions with org from the token — there is no {org_id} path segment on chat. Diagnostic org probes exist to verify path binding for integrators building org-prefixed URLs in later phases.

Permission and agent headers

Every protected proxy request carries:

Authorization: Bearer ibex_pat_<uuid>_<secret>
X-IBEX-Agent-ID: <agent-uuid>

The agent UUID must reference an active row in ibex_core.agents where agents.org_id equals the token's org. Suspended agents return 403 AGENT_SUSPENDED.

Seed data for local dev

bash

make db-migrate
make db-seed

Entity	Fixed UUID (dev seed)
Organization	`00000000-0000-0000-0000-000000000001`
Agent	`00000000-0000-0000-0000-000000000003`
Token	`00000000-0000-0000-0000-000000000004`

make db-seed exports IBEX_DEV_ORG_ID, IBEX_DEV_AGENT_ID, and IBEX_DEV_TOKEN for smoke tests. Seed refuses non-local DSN hosts and IBEX_ENV=production.

Projects (reserved)

The ibex_core schema includes hooks for project-scoped resources — memories, directives, and dashboard namespaces will attach to projects in Phase 3+. Phase 1 operators should:

Issue one PAT per integration environment (dev/staging/prod org)
Register one agent per autonomous service instance
Avoid assuming project IDs exist in API paths yet

Multi-tenant security layers

HTTP middleware

Proxy extracts org_id from validated token; rejects path mismatches.

gRPC handler

Auth validates org_id in CreateToken/ValidateAgent requests.

Store layer

Every query includes org_id in WHERE clauses.

Postgres RLS

Session org context gates row visibility — see Multi-tenant RLS.

Defense-in-depth rationale: Tenant isolation.

Verify org binding

bash

curl -s "http://localhost:8080/v1/orgs/${IBEX_DEV_ORG_ID}/auth-probe" \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}"

CI security-integration runs automated cross-tenant cases — no manual probing required for merge gates.

Multi-tenant RLS — database enforcement
Issuing API keys — PAT lifecycle
Proxy authentication — header contract
Concepts — integrator-oriented overview

Was this page helpful?

Entity hierarchy

+--------------+      +------+         
| ORGANIZATION ||---o<| USER |         
+--------------+ has  +------+         
        |                 |            
    ------issues----------- may_create 
    |   |          |      |            
   o<   |         o<      |            
+-------+      +-------+               
| AGENT ||---o<| TOKEN |               
+-------+may_bi+-------+

Organization

Top-level tenant. Owns agents, tokens, and rate-limit buckets. Table: ibex_core.organizations.

User

Human operator (Phase 1 subset). Linked to org membership for token issuance audit. Table: ibex_core.users.

Agent

Autonomous actor that calls the proxy. Identified by X-IBEX-Agent-ID on every protected request. Table: ibex_core.agents.

Token

PAT credential with permission bitmap, bound to org (and optionally user/agent). Table: ibex_core.tokens.

Full schema reference: Data model.

Runtime binding rules

Rule	Enforcement
Token org is authoritative	Proxy middleware after `ValidateToken`
Agent must belong to token org	`ValidateAgent` gRPC + store WHERE clause
Path org must match token org	`/v1/orgs/{org_id}/auth-probe` only
Cross-tenant access	`403` — never `404`

Permission and agent headers

Every protected proxy request carries:

Authorization: Bearer ibex_pat_<uuid>_<secret>
X-IBEX-Agent-ID: <agent-uuid>

The agent UUID must reference an active row in ibex_core.agents where agents.org_id equals the token's org. Suspended agents return 403 AGENT_SUSPENDED.

Seed data for local dev

bash

make db-migrate
make db-seed

Entity	Fixed UUID (dev seed)
Organization	`00000000-0000-0000-0000-000000000001`
Agent	`00000000-0000-0000-0000-000000000003`
Token	`00000000-0000-0000-0000-000000000004`

make db-seed exports IBEX_DEV_ORG_ID, IBEX_DEV_AGENT_ID, and IBEX_DEV_TOKEN for smoke tests. Seed refuses non-local DSN hosts and IBEX_ENV=production.

Projects (reserved)

The ibex_core schema includes hooks for project-scoped resources — memories, directives, and dashboard namespaces will attach to projects in Phase 3+. Phase 1 operators should:

Issue one PAT per integration environment (dev/staging/prod org)
Register one agent per autonomous service instance
Avoid assuming project IDs exist in API paths yet

Multi-tenant security layers

HTTP middleware

Proxy extracts org_id from validated token; rejects path mismatches.

gRPC handler

Auth validates org_id in CreateToken/ValidateAgent requests.

Store layer

Every query includes org_id in WHERE clauses.

Postgres RLS

Session org context gates row visibility — see Multi-tenant RLS.

Defense-in-depth rationale: Tenant isolation.

Verify org binding

bash

curl -s "http://localhost:8080/v1/orgs/${IBEX_DEV_ORG_ID}/auth-probe" \
  -H "Authorization: Bearer ${IBEX_DEV_TOKEN}" \
  -H "X-IBEX-Agent-ID: ${IBEX_DEV_AGENT_ID}"

CI security-integration runs automated cross-tenant cases — no manual probing required for merge gates.

Multi-tenant RLS — database enforcement
Issuing API keys — PAT lifecycle
Proxy authentication — header contract
Concepts — integrator-oriented overview

Was this page helpful?