Architecture
GrayPass separates evidence collection, policy decisions, and business execution. This separation lets your application bind a decision to the exact action it intends to perform, while keeping credentials and final authorization off the browser.
Components and request path
Your backend connects browser collection to a server decision, then enforces that decision at the business operation.
| Component | Responsibilities | Trust boundary |
|---|---|---|
| Customer browser | Collect permitted derived evidence; display immutable action details; complete an action-bound challenge | Requires a trusted page and endpoint |
| Customer backend | Authenticate the user; resolve subject and resource; validate and freeze request material; request a decision | Holds the server credential and business authorization rules |
| GrayPass API | Enforce tenant and environment scope; assess evidence; apply the active policy; issue and track proofs | Supplies decisions and proof state to the customer transaction |
| Customer execution service | Verify expected proof bindings; consume online; execute once through its own durable state | Requires backend verification against the saved request |
| Console | Configure environments, integrations, actions and policies; inspect activity and evaluations | Permissions depend on the authenticated role and environment |
The browser obtains a short-lived client token from an authenticated route on your backend. That token is bound to one subject and registered origin. The SDK opens an enrollment or observation session and sends signed evidence windows. Your backend submits an action request with subject, session where available, resource, context, audience, time, nonce, and idempotency key.
The decision contains the policy version and the Assurance Profile used. An enforce-mode allow can carry a short-lived signed proof. Your backend compares the proof with request material it already trusts, checks current status and one-time consumption, and only then performs the action. Outcome reporting closes the operational loop.
Tenant and environment isolation
A tenant is the customer's administrative boundary. An environment is a distinct sandbox or live boundary inside that tenant. Credentials, subjects, sessions, actions, policies, traces, and proofs are scoped accordingly. Keep each environment’s credentials, subject mapping, and pending requests together so requests and verification use the intended scope.
Sandbox supports integration exercises, including explicitly labeled simulated confirmation and proof-backed execution. Live shadow traffic evaluates real policies alongside your existing application path. Review the applicable production-shadow meter in Usage and billing.
Evidence and authorization are different objects
A Brainprint is a private, tenant-scoped learned behavioral model. An Assurance Profile describes typed claims, their coverage, freshness, limitations, and version information. A decision applies a particular policy to an action request. A proof binds the allowed request for a relying party. Your application supplies the authenticated session and account permissions for this flow.
Derived evidence avoids transmission of typed characters and raw interaction paths, but it remains security-relevant data associated with a pseudonymous subject. Customer-supplied context can contain sensitive information if the customer puts it there. Prefer a digest or opaque identifier over bank details, document text, or free-form user content.
Response handling and recovery
When evidence is missing or stale, the policy selects a challenge, hold, or denial. Handle that decision through its defined workflow. For an API or verifier timeout, preserve the pending operation and reconcile its state before continuing. Complete online verification to check current revocation and consumption state.
GrayPass proof consumption and your application database are separate transactions. Your application needs its own request ledger, idempotency discipline, locking, and recovery process. Use the integration guide to implement recovery across those two transactions.
Deployment requirements
The integration described here uses the hosted GrayPass service with a browser application and customer backend. Review the security controls, threat model, and commercial model against your deployment requirements. Confirm any required service commitment or deployment arrangement in your agreement before depending on it.