GrayPass
Docs
Download PDF
For agents

Sandbox quickstart

Run a complete GrayPass integration: enroll a subject, request a policy decision, confirm an action, verify its proof, and update a fictional payout destination. The standalone example includes a browser interface, Node backend, demonstration account, and SQLite request ledger. All destination changes stay in the local example.

Prerequisites

Use Node.js 22.17 or later in the Node 22 line and a current desktop Chromium browser for the reference walkthrough. The documented automated walkthrough runs in Chromium. You also need the three downloads below and a sandbox admin credential. Request workspace access through Getting started. Admin scope lets this example create its action and policy as well as request runtime decisions.

In Console, select the sandbox and register http://localhost:3100 as an allowed origin. Download the browser core archive, Node archive, example archive, and checksum manifest. Place all four files in one working directory. The browser core package supplies the collection used in this exercise.

Verify and install

Shell
shasum -a 256 -c SHA256SUMS.txt

Expect each archive to report OK. On Linux, use sha256sum in place of shasum -a 256. If verification fails, obtain a fresh copy before continuing.

After verification succeeds, unpack the example, install the SDKs, and run its tests:

Shell
unzip graypass-quickstart-1.0.1.zip
cd graypass-quickstart
npm install --ignore-scripts ../graypass-node-1.0.0.tgz \
  ../graypass-browser-core-1.0.1.tgz
npm test

The example uses the prebuilt SDKs and npm test should pass after installation. Keep the supplied checksums and generated dependency lockfile.

Set GRAYPASS_SECRET_KEY in your shell using your approved secret-handling process, then start the example:

Shell
GRAYPASS_ENDPOINT='https://app.graypass.org' npm start

Open http://localhost:3100. The example checks the sandbox credential, prepares its subject and action, and serves the page on the local loopback interface. Keep GRAYPASS_SECRET_KEY in the backend environment throughout the exercise.

Follow the exercise

  1. Start enrollment and interact normally with the local page. Read accepted coverage rather than counting seconds yourself.
  2. Complete enrollment when the server reports readiness. The application moves to observation for the same subject.
  3. Submit the mock destination change in shadow mode. Inspect the hypothetical decision. The example must leave its destination unchanged.
  4. Use the explicitly labeled sandbox enforce control. Submit a new mock request and inspect any challenge or hold.
  5. Complete the labeled simulated confirmation when offered. Use this simulation to test the request chain. The passkey workflow is covered in Decisions.
  6. The backend resolves the resulting authorization, verifies the independently bound request, verifies and consumes the proof online, and applies the local mock destination change once.
  7. Inspect the recorded authorization and outcome, then use the subject lifecycle and local cleanup instructions in the example README.

For a hold, inspect the reason codes and follow the review path in Decisions. Use Troubleshooting to resolve credential, collection, or configuration responses.

Check the result

The exercise is complete when you can inspect these results:

Step Expected result
Verify downloads All three archives report OK
Run package tests The test summary reports zero failures
Enroll Accepted coverage advances and enrollment_ready becomes true
Submit in shadow An authorization and reasons appear; the mock destination retains its previous value
Complete an eligible enforce request The backend verifies and consumes the proof, updates the local destination once, and records the outcome

An authorization includes fields such as decision, mode, reason_codes, and trace_id. In the Node SDK, verification.actionHash identifies the locally bound request. Retain those fields to follow the same operation in Console Activity.

Understand the integration

The browser receives a scoped client token and observation session, while the secret credential stays on the backend. The backend chooses the fixture subject and merchant and freezes the exact proposed destination. Its pending request stores the action binding and original authorization association. Resume requests cannot substitute another destination or child authorization.

The example includes CSRF controls and a local request ledger. When adapting it, connect your authenticated account adapter and transactional store, then implement the crash-recovery procedure for proof consumption and business execution.

Clean up

  1. Select Stop collection, close the page, and stop the local server.
  2. Reconcile any pending request in the example ledger and retain the outcome records you need.
  3. Delete the sandbox subject through Console or deleteSubject() using its stored identifier.
  4. Retire the example action and revoke its test credential when finished.
  5. Remove the local data/ directory after completing reconciliation and retention.

The archive README describes how to locate the subject identifier and inspect the local ledger.

Adapt the example

Replace the fixed demonstration account with your application’s authenticated account and resource-ownership checks. Separate admin setup from runtime credentials, move the request ledger to your transactional store, and implement operational recovery before connecting a real business mutation. Integration explains those responsibilities.

For an evaluation alongside an existing application, keep its business path in place and use shadow evaluation. Follow Production operation to plan monitoring, request recovery, and operational ownership.