Security Model

Read this before integrating anything beyond your own local development environment.

Current limitations (honest, as of Developer Platform v1)

• The Authorization: Bearer header is accepted but not enforced. The SDK sends it if you configure apiKey; the engine accepts any value, or none. Do not treat this as authentication.
• X-Tenant-ID is an architectural placeholder, not a security boundary. It scopes reads/writes to the named tenant (agents, sessions, runs, and records are stamped and filtered by it, and a cross-tenant lookup returns 404), but there is no verification that a caller is entitled to act as the tenant it claims. Anyone who can reach the engine can set any X-Tenant-ID value.
• No tenant authentication exists yet. user_role and submitted_by are caller-declared fields, not authenticated identity claims.
• No real patient data should ever be sent to this platform. Every synthetic case, source, and example in this documentation uses fabricated data.
• No production deployment claims are made. This is a local development / evaluation platform in its current form.
• No hospital identity integration exists (no SSO, no IAM-issued role claims).
• No EHR/FHIR integration exists. All clinical context is synthetic and supplied directly by the caller.
• Policies are global across all tenants in this version — there is no per-tenant policy configuration yet.

Customer-owned model credentials (Initiative 2/3)

Managed execution (POST /runtime/agents/:agentId/execute) requires a tenant-owned Provider Connection, reached through an Execution Profile — CARC (Giggle AI Innovation) never pays for or supplies model credentials on a customer's behalf. The precise guarantee:

• A RegisteredAgent needs an execution_profile_id, and that ExecutionProfile needs both adapter_id and provider_connection_id set, before managed execution will run; there is no fallback path that substitutes a different profile, connection, or a shared credential when any of these is missing.
• Both the ExecutionProfile and the ProviderConnection it references are always looked up scoped to the requesting agent's own tenant_id — a tenant can never resolve, and therefore can never execute against, another tenant's profile or connection. This includes Giggle AI Innovation's own internal/demo connection and profile (seeded only under the engine's configured default tenant at boot) — exactly as unreachable from any other tenant as any other tenant's resources would be.
• Because X-Tenant-ID remains an unauthenticated placeholder (see above), a caller who can set X-Tenant-ID to the engine's configured default tenant already inherits whatever that tenant has access to — this is the same pre-existing limitation described throughout this page, not a new one introduced by Provider Connections or Execution Profiles. Run this platform only in trusted environments, as stated below.
• Raw provider credentials are never stored in a RegisteredAgent, an ExecutionProfile, an AgentRun, a DecisionContextRecord, a RuntimeEvent, a log line, or any API response — only an opaque credential_reference pointer on ProviderConnection (see Provider Connections). ExecutionProfile itself has no field that could ever hold a credential.
• Agents registered before Initiative 3 with the old adapter_id+ provider_connection_id shape are transparently migrated to an auto-created ExecutionProfile at the HTTP boundary — this migration shim never accepts a caller-supplied "internal/demo" flag, so it cannot be used to point a customer tenant at Giggle's own credentials either.

What tenant scoping does give you today

Even without a security boundary, X-Tenant-ID is useful during development and evaluation:

• The same external agent_id can be registered independently by two different tenants without colliding.
• agent_id uniqueness is enforced per-tenant, not globally.
• Listing/getting agents, sessions, runs, decision records, and metrics is scoped to the resolved tenant — useful for keeping demo/evaluation data separate without deploying separate engine instances.

Resolution order: X-Tenant-ID request header → SDK tenantId config → the engine's DEFAULT_TENANT_ID environment variable → the constant tenant_default.

Intended production direction

The following are on the roadmap, not implemented:

• API keys — real, verified credentials replacing the current accepted-but-unchecked bearer token
• Service identities — authenticated machine-to-machine identity for external agent integrations, replacing caller-declared submitted_by
• Tenant isolation — X-Tenant-ID backed by real authentication, so it becomes an actual security boundary
• Role-based access control — user_role backed by real IAM/SSO-issued claims, replacing the current caller-declared field
• Audit access control — restricting who can read Decision Context Records and export audit trails
• Hospital-controlled deployment — this platform designed to run inside a hospital's own infrastructure boundary, not as a shared multi-tenant SaaS

What to do today

• Run this platform only in trusted, non-production environments
• Use only synthetic data — never real patient information
• Treat X-Tenant-ID and Authorization as integration-readiness placeholders, not access controls, when designing your own system around this platform