> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Jev to Your NSR Workspace

> Configure organization credentials, run evidence-aware Playground cases, and distinguish saved decisions from fresh policy tests.

Use this path when you need private organization policies and editable evidence rather than the
fixed public demo. It requires a console and engine deployment with the latest Jev integration
support. Source availability alone does not establish that your deployment has enabled it.

## Choose the credential path

| Path               | Credential behavior                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Public `/jev` demo | Visitor Jev key is supplied per request; no saved organization connection                                        |
| Signed-in console  | Backend loads the selected organization's saved Jev key for proxied requests                                     |
| Direct NSR API     | Caller supplies ordinary NSR authentication and its own request-scoped Jev key; console storage is not consulted |

A Jev key and an NSR key serve different purposes. Do not exchange their headers or embed either
in customer messages, policy facts, decision JSON, or committed example files.

## Connect in API setup

<Steps>
  <Step title="Select the intended organization">
    Sign in to [the NSR console](https://nsr.stateset.com) and open **API setup → Jev integration**.
    Organization owners/admins or users with integration-management permission can manage the
    connection. Ordinary members can read status but cannot retrieve the secret.
  </Step>

  <Step title="Verify and save the key">
    Enter your Jev key and supported model alias, then choose **Verify and save Jev key**.
    This runs a real synthetic judgment through NSR before saving; it consumes provider usage.
    The verification has no authorizing business rule and performs no business action.
  </Step>

  <Step title="Check the connection evidence">
    Inspect connection status, verification time, and resolved model. Use **Test saved connection**
    when you deliberately want another provider check. A status page alone is not a perpetual
    health guarantee.
  </Step>
</Steps>

The backend stores organization credentials in Vault and never returns the saved secret to the
browser. It selects credentials from the authenticated organization, strips caller-supplied Jev
headers on the proxied path, and injects the saved key server-side. Storage errors fail closed;
they do not silently switch an intended customer-key request to the platform key.

**Disconnect Jev key** disables that stored connection for future calls. The engine may then
use its platform configuration, if available. Disconnect does not revoke the key at the provider;
revoke or rotate it there when needed. Vault retention policy governs historical versions.

## Run an evidence-aware Playground case

1. Open **Playground** and select an industry pack and scenario.
2. Inspect the facts, rules, customer message, Jev questions, and evidence requirements.
3. Use **Guided** editing for supported evidence fields or **Advanced JSON** for the full inputs.
4. Enable Jev and confirm the intended connection. Inline setup can connect a key without
   discarding the draft when supported by the deployed UI.
5. Submit one case, then inspect the decision explanation, model readings, evidence handling,
   rule result, and any required human review.

The signed-in path can edit policy/evidence inputs; the public demo cannot. Loading a standard
non-Jev example clears Jev inputs so the workflows do not mix. Browser drafts contain inputs,
not credentials; avoid putting sensitive customer content in locally saved examples.

<div className="ss-checkpoint">
  **Complete when:** you can identify the model reading, explain which evidence was admitted,
  and point to the policy condition behind the verdict. An approval is not required to complete
  this exercise, and no external business action is implied.
</div>

## Save policy tests without confusing them with proof replay

Under **Saved policy tests**, give the current inputs a name and an expected decision, then
choose **Save current inputs as test**. The current UI stores up to ten named cases per
organization in this browser. This is not a shared server-side test suite.

Before running the saved cases:

* Choose whether to use each saved policy or **Use current rules and evidence requirements for all cases**.
* Review the displayed request count and provider/NSR usage implications.
* Inspect evidence timestamps: saved timestamps remain fixed and can become stale.
* Expect Jev-enabled tests to make fresh, potentially varying model calls.

Tests stop on errors and do not automatically retry. Download the report to retain the requests,
observed outcomes, readings, and policy pins when returned. A matching expected decision is not
independent verification of the proof bundle.

## Inspect an original decision

Decision history can expose the original record and JSON download. Restore Jev inputs and the
authorization goal only when the engine captured them; treat a missing snapshot as missing.
Running a reconstructed request makes a new decision, not a reproduction of the original model
inference. Use the supported engine verification bundle for evidence-aware runs rather than
the console's basic browser proof replay.

If a complete history CSV fetch fails, the console labels the export partial and uses a
`-partial` filename. Do not treat that file as a complete decision ledger.

## Connect a direct API client

First verify the engine capability using your normal tenant-scoped credentials. Set
`NSR_BASE_URL` to the engine origin with no `/v1` suffix:

```bash theme={null}
: "${NSR_BASE_URL:?Set your NSR engine origin}"
: "${NSR_API_KEY:?Set your NSR API key}"
: "${NSR_ORG_ID:?Set your authorized organization ID}"
curl --fail-with-body --silent --show-error \
  "${NSR_BASE_URL%/}/v1/integrations/jev/capabilities" \
  -H "X-API-Key: ${NSR_API_KEY}" \
  -H "X-Org-ID: ${NSR_ORG_ID}"
```

Require `request_scoped_credentials: true` and `provider: "jev"` before sending a Jev secret.
For a reviewed decision payload exported or generated from your current Playground inputs:

```bash theme={null}
: "${NSR_BASE_URL:?Set your NSR engine origin}"
: "${NSR_API_KEY:?Set your NSR API key}"
: "${NSR_ORG_ID:?Set your authorized organization ID}"
: "${JEV_API_KEY:?Set your Jev API key}"
curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 120 \
  "${NSR_BASE_URL%/}/v1/decisions" \
  -H "X-API-Key: ${NSR_API_KEY}" \
  -H "X-Org-ID: ${NSR_ORG_ID}" \
  -H "X-NSR-Jev-Key: ${JEV_API_KEY}" \
  -H 'X-NSR-Jev-Model: jev-latest' \
  -H 'Content-Type: application/json' \
  --data-binary @jev-decision-request.json
```

Create and inspect `jev-decision-request.json` first; it is not supplied by this guide. It must
be a full decision request, not the public demo's `{industry, scenario}` body. Use HTTPS outside
local development and your actual authorized organization. Ordinary NSR tenant authorization
still applies. The engine removes Jev headers and scopes the credential to that request;
supplying a model header without a key is rejected.

## Deployment and recovery checks

| Symptom                                       | Check                                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Secure key entry is unavailable               | Console Vault configuration and credential-store availability                                    |
| Save verification fails                       | Engine capability, provider configuration, key validity/quota, and the synthetic judgment result |
| You can see status but cannot replace the key | Organization role or integration-management permission                                           |
| Direct SDK calls do not use the saved key     | Expected: console storage applies to proxied console requests only                               |
| Disconnected key but Jev still runs           | Whether the engine has platform credentials configured                                           |
| Test expectation differs from the result      | Actual readings, evidence admission/freshness, current versus saved policy, and review signals   |

Deployment owners should release the engine support before enabling console credential setup,
use the real `typesafe` judgment provider rather than `fixture`, and configure shared Vault
storage with a scoped service identity. Customer keys are restricted to the TypeSafe provider
origin; the client does not choose a credential-forwarding URL. The public demo additionally
needs its dedicated tenant/key and the configured shared limiter; these are separate from a
customer's private organization connection.

Related: [Jev + NSR concepts](/stateset-nsr-jev), [public first decision](/guides/jev-first-decision),
and [agent execution gate](/stateset-nsr-agent-gate).

Source basis: `nsr-app/server/jev.mjs`, `server/jev-store.mjs`, `JevSettings.tsx`, `PolicyChecks.tsx`,
Playground and decision-history components, and `stateset-nsr/src/api/jev_credentials.rs`,
reviewed 2026-09-20. Live provider calls and production credential storage were not exercised.