Concepts and lifecycle
An integration connects a person in your application to evidence sessions and decisions about particular actions. Keep its identifiers separate: one subject can have many sessions, and one business request can have an initial authorization followed by a challenge or review result.
Core objects
| Object | Meaning | Lifecycle consideration |
|---|---|---|
| Tenant | Customer administration and isolation boundary | Select explicitly when operating multiple customers |
| Environment | Sandbox or live scope | Resources and credentials belong to one environment |
| Subject | Pseudonymous person record mapped from your authenticated account | Enroll, revoke, recover, export, or delete |
| Brainprint | Private behavioral model associated with a subject | Supplies continuity evidence; adaptation can be frozen |
| Session | Enrollment or observation interval | Evidence belongs to the subject and purpose; end on exit |
| Evidence window | Signed derived measurements over an interval | Acceptance, replay checks, quality, and active time affect coverage |
| Assurance Profile | Typed evidence claims and limitations | Assessed at a time, with explicit versions and freshness |
| Protected action | Registered consequential operation | Stable key plus current mode and active policy |
| Policy version | Immutable requirements and request constraints | Create a version, then activate it; retain version identity |
| Authorization | Decision for one bound request | Can lead to challenge or review and a child authorization |
| Proof of Agency | Signed artifact for an enforceable allow | Short-lived; check scope, current status, and consumption |
| Outcome | What the application actually did | One immutable report per authorization |
Subject lifecycle
A newly created subject is ready to begin enrollment. An enrollment session gathers permitted evidence until the server reports readiness. Your backend completes enrollment; an observation session can then supply fresh evidence for action requests. Use the server's enrollment_ready field to drive completion.
Revocation ends the subject's ability to continue on existing evidence and credentials. Recovery follows the subject's declared policy and requires your application to establish the appropriate anchor. Deletion removes the subject's supported operational data; billing records, security audit records, and backups have separate handling described in Privacy.
Action lifecycle
Register a descriptive action key such as payout.destination.change. Define what resource it changes and every security-relevant request field. Configure an immutable policy and activate it. New actions begin in shadow mode. Test and shadow requests evaluate the policy without generating an enforceable proof. Enforce mode requires a proof for the exact request before execution. Exercise that path in sandbox around a mock operation before connecting a business mutation.
The customer request ledger should assign a stable logical request ID. Retrying the same request reuses the same idempotency key and request material. Changing the destination, subject, resource, or another bound value creates a different action request. A challenge preserves the original request binding through approval.
Four decisions
allow means the evaluated policy permitted the request. The application still checks mode, proof, account permission, and business invariants. challenge requires an action-bound approval step. hold pauses the operation for review. deny blocks it.
insufficient_evidence is a claim status and reason. Policy maps it to challenge, hold, or deny. coverage describes the amount and variety of accepted evidence; freshness_ms describes its age. Interpret both alongside the categorical claim status.
Trace and outcome lifecycle
Keep the original authorization ID with your pending business request. A completed challenge or an approved review can produce a child authorization. Resolve that child from your backend and verify its relation to the original request. Treat the browser-returned ID as a lookup reference and verify the retrieved record.
After executing or refusing the business operation, report what actually occurred. A repeated identical outcome is idempotent; a contradictory report is rejected. Define who can assign each outcome and retain the evidence for that assignment in your application. Evaluate GrayPass explains how those labels contribute to a report.
Continue with Actions and policies, Decisions and challenges, and Proofs and verification.