Security

GrayPass adds action-specific assurance to an application that already authenticates and authorizes its users. The customer backend decides which business operation is being attempted, requests a GrayPass decision, verifies any resulting proof, and controls execution. Execution follows the verified authorization for the saved request.

Read this chapter with the threat model and proof verification guide. Keep your existing authentication, authorization, and transaction controls in place: GrayPass assurance adds evidence at the protected action boundary.

Credentials and scope

Credential or identity	Intended holder	Security responsibility
Server API credential	Customer backend	Keep in a secret store; use only for its tenant and environment.
Administrative credential	Restricted control plane	Use for action, policy, and lifecycle administration; separate from ordinary application execution.
Browser client token	One authenticated subject in an allowed origin	Obtain from your backend after checking the application session; keep short-lived and avoid persistent browser storage.
Console membership	Named administrator or reviewer	Grant the role needed for the person's work and review access when responsibilities change.
Webhook signing secret	Customer webhook receiver	Verify the exact request bytes, freshness, and duplicate event handling before processing.

Do not embed a server or administrative credential in a page, mobile package, screenshot, support ticket, or source repository. Browser tokens are constrained credentials; they are still sensitive. A browser token can submit evidence, obtain bounded status, and perform permitted challenge ceremonies. It cannot request an authorization or obtain a canonical Proof of Agency.

Tenant and environment checks apply to data access. Sandbox and live environments have separate identifiers and proof-signing keys. An application must verify both the environment kind and the expected tenant/environment identifiers; the word live by itself does not identify your environment.

Action and proof integrity

A Proof of Agency is an ES256 signed JWS. It binds a decision to the intended audience, subject, action, resource, context, actor where applicable, nonce, and validity interval. Build the action description from server-authoritative records. Include every value that could change the consequence of the operation, such as the exact amount and destination fingerprint.

Before executing an operation:

Require a final allow decision in the intended enforcement mode.
Verify the signature using the expected issuer's keys and a supported algorithm.
Check issuer, audience, tenant, environment, subject, action, nonce, and time claims.
Compare the proof's action hash with the hash of your stored, independent pending request.
Verify current proof state online and consume the proof before execution.
Commit the business operation through your own durable idempotency and transaction controls.

Online verification checks current revocation and consumption state. Use your application ledger to recover across proof consumption and the business commit, following Integration.

Evidence and endpoint trust

The browser SDK summarizes interaction locally. Evidence frames are authenticated to their session and checked for replay and malformed values. Session authentication establishes possession of the session key. Pair it with the endpoint controls described in Endpoint security.

Continuity compares session behavior with the enrolled Brainprint; change indicators describe changes within the observed session. Interpret these through the typed Assurance Profile, including evidence quality, freshness, and limitations. Your account controls establish enrollment identity, and your device controls establish endpoint trust. Passkeys add a verified authenticator ceremony for the bound challenge. Review Endpoint security when selecting the transaction-confirmation path.

Encryption and operational boundaries

The hosted service uses HTTPS. Stored templates and certain recoverable proof/request material are encrypted at the application layer. Proof signing uses managed asymmetric keys, with separate sandbox and live keys.

Apply access control, context minimization, and proof verification alongside encryption. GrayPass processes the evidence and request fields needed to produce a decision. Your backend and any system that receives a proof also need appropriate retention and access policies.

Confirm availability, support, backup handling, and recovery commitments during procurement; the applicable agreement defines those commitments. Request supporting material for the specific controls your security review requires.

Safe operation

Use separate credentials and application configuration for development and production. Rotate exposed credentials immediately, then examine action and administrative activity. A credential rotation does not replace subject revocation, proof-status checks, or webhook-secret rotation: each protects a different boundary.

Keep action policy changes under change control. Test insufficient evidence, timeouts, expired proofs, subject revocation, and changed transaction payloads. An unavailable assurance service must lead to the explicit customer-defined safe path, such as retry, hold, or another approved verification process; it must not silently execute the protected operation.

Vulnerability reporting and review material

Report suspected vulnerabilities privately to founders@graypass.org. Include the affected surface, approximate time, a synthetic reproduction, and the impact you observed. Do not send credentials, private keys, raw behavioral data, or customer records.

For a security questionnaire or a request for supporting evidence, contact founders@graypass.org with the controls you need to assess and the intended reviewers. The scope and permitted recipients of controlled security material are agreed separately.