Concepts
Shared responsibility
What the consuming product, Deeplinq, the identity provider, and the deployment owner each control.
Deeplinq is an engine inside a product, not the product's identity system or payment processor. A production integration works when each boundary has one clear owner.
| Concern | Consuming product or partner | Deeplinq engine | Deployment owner |
|---|---|---|---|
| Product identity | Chooses the application and user experience | Verifies signed tokens and resolves them to engine principals | Operates Keycloak and its realms, organizations, clients, and memberships |
| Tenant placement | Sends users through the correct organization sign-in | Requires one bound organization claim; never guesses or auto-provisions | Creates and maintains the engine↔provider identity binding |
| Authorization | Decides who should receive elevated access | Enforces engine-held roles, model grants, resource grants, and ownership | Grants and revokes roles through the admin surfaces |
| Model access | Chooses the product experience and requested model | Routes only to entitled, priced, enabled connectors | Registers connectors, pricing, grants, credits, and guardrails |
| End-user data | Owns notice, consent, and the product's source records | Isolates tenant data and applies retention, deletion, screening, and audit rules | Operates PostgreSQL, object, vector, and optional memory stores |
| Provider credentials | Never exposes them to a browser or mobile client | Seals connector and OAuth credentials at rest | Stores deployment secrets and controls egress |
| Billing | Owns checkout and payment-provider processing | Owns credits, holds, usage, limits, and reconciliation records | Funds organizations or calls the billing top-up surface |
| Availability | Handles typed failures and degraded product states | Fails closed when a configured governed dependency is unavailable | Monitors readiness, capacity, backups, and recovery |
Boundaries that must not blur
- An application is one product and one Keycloak realm. A realm is a user namespace, so the same email in two applications is two unrelated people.
- An organization is one customer inside that application. Its provider organization is explicitly bound to one engine organization.
- A subject is the identity provider's identifier. A principal is the engine's stable identifier. Grants, ownership, limits, and teams use the principal.
- A machine token represents a backend, not a person. It cannot reach user-owned conversations, connections, memories, or agent runs.
- The engine processes credits, not payments. A payment service calls the idempotent billing top-up endpoint after money has settled elsewhere.
Handoff package for a consuming team
Give every integration team:
- the engine base URL;
- the application name and issuer;
- the engine organization UUID and provider organization alias;
- either a machine client or the end-user sign-in contract;
- the granted models, enabled capabilities, and commercial limits;
- the integration checklist;
- the support path and the
X-Request-IDthey must retain from failures.
Never hand over platform-administrator credentials, deployment secrets, or provider connector keys.