GETTING STARTED

Test Mode / Sandbox

Test mode lets you integrate Fidacy safely before going live. Assessments run through the full pipeline — same validation, same signed verdict — but are flagged livemode: false so they are clearly distinguished from production traffic.

What test mode is

Test and live modes share the same engine, the same policy evaluation, the same risk scoring, and the same EdDSA-signed verdict. The only difference is a flag: when you authenticate with a fky_test_ key, every resulting assessment carries outcome.livemode: false. There is no separate data store, no separate endpoint, and no separate billing record.

Create a test key

Pass "mode": "test" to POST /v1/api-keys. The raw key is returned once in the key field and cannot be recovered — store it securely.

POST/v1/api-keys

curl https://api.fidacy.com/v1/api-keys \
  -H "Authorization: Bearer $YOUR_KEYS_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my sandbox key",
    "scopes": ["assess:write"],
    "mode": "test"
  }'

Response (201):

{
  "id": "key_…",
  "name": "my sandbox key",
  "prefix": "fky_test_xA",
  "scopes": ["assess:write"],
  "key": "fky_test_xA8Qd…"   // shown once, save it now
}

Keys created without a mode field default to "live" and carry the prefix fky_live_.

Use the test key

Send the fky_test_ key as you would any API key — in x-api-key or as a Bearer token. The engine detects the prefix at auth time and sets livemode: false on every assessment that follows.

{
  "decision": "approve",
  "score": 12,
  "assessmentId": "asmt_…",
  "riskPayloadJws": "eyJhbGciOiJFZERTQSJ9…",
  "outcome": {
    "object": "assessment",
    "livemode": false,
    "outcome": { "decision": "approve", "risk_level": "normal", "reason": "approved" }
  }
}

One org, two modes. Test and live keys belong to the same organization — there is no separate test account. Switch environments by choosing which key you pass. The livemode flag is set by the engine from the authenticating key prefix, not by anything in the request body.

Revoking a test key

Test keys follow the same lifecycle as live keys. Revoke one when you no longer need it:

curl -X POST https://api.fidacy.com/v1/api-keys/:id/revoke \
  -H "Authorization: Bearer $YOUR_KEYS_WRITE_KEY"

Signed verdict

The riskPayloadJws is issued exactly as in production, verifiable against the public JWKS at /.well-known/jwks.json.

Identical errors

All error codes, HTTP statuses, and response shapes are identical between test and live modes.

No test-only routes

Every call goes to the same API surface; only the key prefix changes the behavior.

← PREVIOUS
Authentication NEXT →
How Fidacy Works