Agent identity patterns

Authentication vs. authorization

Two distinct security concerns operate at different points in every agent request. Conflating them leads to the classic failure mode: a bot that either leaks data across users or returns nothing useful to anyone.

IAM and Gateco are complementary, not overlapping:

Three integration patterns

Choose the pattern that matches your channel and identity requirements.

# Python SDK
result = client.retrievals.execute(
    connector_id="conn_abc",
    principal_id="bot-service-principal-uuid",   # ← service account UUID
    query_vector=[...],
    top_k=10,
)

// TypeScript SDK
const result = await client.retrievals.execute({
  connectorId: "conn_abc",
  principalId: "bot-service-principal-uuid",
  queryVector: [...],
  topK: 10,
});

# Python SDK — pass email; Gateco resolves to principal UUID
result = client.retrievals.execute(
    connector_id="conn_abc",
    principal_id=client.principals.resolve(email="alice@acmecorp.com").id,
    query_vector=[...],
    top_k=10,
)

# MCP server — email parameter passed directly; resolution is automatic
# gateco_retrieve(query="...", email="alice@acmecorp.com", connector_id="conn_abc")

# Planned API shape (not yet available)
result = client.retrievals.execute(
    connector_id="conn_abc",
    external_subject={
        "channel":    "whatsapp",
        "subject_id": "+1-555-0142",
        "attributes": { "tenant_id": "customer_123" },
    },
    query_vector=[...],
    top_k=10,
)

Identity resolution

For Pattern 2, the agent resolves an employee to a Gateco Principal UUID before calling retrievals.execute(). The POST /api/principals/resolve endpoint accepts either email or provider_subject and returns the active principal for that identity.

• →Returns 404 for unknown or inactive identities — never creates a principal. IDP sync must have run first.
• →Resolution is read-only. Treat 404 as “user not in IDP yet” — surface a clear error in the agent rather than falling back to a default principal.
• →The MCP server resolves automatically when you pass email — no explicit resolve call needed in the agent runtime.

Policy conditions for agent flows

Gateco policies evaluate three condition namespaces. For agent deployments, the most useful principal-side conditions are:

Resource-side conditions reference the metadata bound to your vectors: resource.classification, resource.sensitivity, resource.domain, resource.labels, and resource.encryption_mode. Always use the resource. prefix — bare field names resolve against the principal, not the resource.

For multi-tenant isolation, a typical policy condition is: principal.attributes.tenant_id == resource.labels.tenant_id. This ensures every retrieval, regardless of which agent issued it, only returns results belonging to the requesting user's tenant.

Audit trail for agent retrievals

Every retrieval is recorded as a SecuredRetrieval event with full context:

• principal_id and principal_name snapshot — who was resolved at retrieval time
• connector_id and connector_name
• query — the search query text
• outcome — allowed / partial / denied
• policy_trace — full decision trace including which policy rules fired and why
• search_mode — vector / keyword / hybrid / grep
• latency_ms and timestamp

For agent deployments, the audit trail answers the question “which user, via which bot, retrieved which data, under which policy?” — the data your compliance and incident-response teams will eventually ask for. It is written automatically; no additional configuration is required.