Getting started

Set up a GrayPass workspace, install the SDKs, and connect your first action. The reference integration changes a fictional payout destination in a sandbox, giving you a complete flow to run and inspect.

Before you begin

You need access to a GrayPass tenant and its sandbox environment, an application backend, a browser application served from an origin you control, and the JavaScript SDK archives described below. The runnable example requires Node.js 22.17 or later in the Node 22 line. Contact founders@graypass.org for account access.

Resolve the GrayPass subject from your authenticated application account and store that mapping on your backend. Your existing authentication and permissions establish who can request the operation.

Configure the sandbox

1. Sign in to the Console and confirm the tenant and Sandbox environment.
2. Open Integrations and register the application's exact origin, including scheme and port where applicable. An origin does not include a path.
3. Create an appropriately scoped sandbox credential. Use a server credential for the runtime path and an admin credential for action and policy setup, or perform setup through the Console.
4. Store the secret credential on your backend. Configure the browser to obtain its short-lived client token through an authenticated backend route.
5. Confirm the credential identity before creating resources.

import { GrayPassClient } from '@graypass/node';

const graypass = new GrayPassClient({
  apiKey: process.env.GRAYPASS_SECRET_KEY!,
  endpoint: 'https://app.graypass.org',
  keysUrl: 'https://app.graypass.org',
});
const identity = await graypass.credential();
if (identity.environment_kind !== 'sandbox') {
  throw new Error('This exercise requires a sandbox credential');
}

This TypeScript excerpt assumes the Node SDK is installed and GRAYPASS_SECRET_KEY is set on your backend. The expected result is a sandbox identity for your tenant. If the tenant, environment, or scope is wrong, replace the credential before creating resources. Keep the secret value out of diagnostic output.

Install the SDKs

Download these files into one directory:

• Browser SDK core 1.0.1
• Node SDK 1.0.0
• Runnable quickstart 1.0.1
• SHA-256 checksums

The browser core package supports observation and challenges. It installs as @graypass/browser. Camera operation has separate asset prerequisites.

Verify all three archives before installing:

shasum -a 256 -c SHA256SUMS.txt

Expect an OK result for each archive. If a checksum fails, discard that copy and download it again before installing. On Linux, use sha256sum in place of shasum -a 256.

After verification succeeds, install the SDKs:

npm install --ignore-scripts ./graypass-node-1.0.0.tgz ./graypass-browser-core-1.0.1.tgz

Keep the checksums and dependency lockfile for repeatable installation. The packages contain prebuilt JavaScript and types; no GrayPass source checkout or build is needed.

Run your first flow

Continue with the Quickstart to enroll a sandbox subject, request a decision, and inspect the resulting trace. The example first leaves the mock destination unchanged in shadow mode, then offers sandbox enforcement so you can follow challenge, proof verification, consumption, and a local destination update. Its README includes cleanup instructions.

When adapting the flow, use Integration for request binding and recovery, then Evaluate to plan a shadow study with your intended users.