Sandbox Testing

The sandbox environment lets you test your integration end-to-end without submitting real identity documents. Use sandbox API keys and test fixtures to get deterministic, predictable results.

Sandbox API keys and base URL

Sandbox uses a separate base URL from production — send your kora_ key to the sandbox host (a sandbox key returns 401 INVALID_TOKEN against the production host):

Environment	Base URL	Key
Sandbox	https://koraidv-identity-sandbox-626704085312.us-central1.run.app/api/v1	kora_…
Production	https://idv.korastratum.com/api/v1/idv	kora_…

# Sandbox — no real document processing
Authorization: Bearer kora_abc123...

# Production — real verifications
Authorization: Bearer kora_abc123...

The cURL examples below read the base URL from $KORAIDV_BASE_URL. It defaults to the production host below to show the request shape — set it to the sandbox base URL (shown above) when testing in sandbox. The mobile SDKs select the correct host automatically from your key prefix.

# For sandbox testing set this to:
# https://koraidv-identity-sandbox-626704085312.us-central1.run.app/api/v1
export KORAIDV_BASE_URL="https://idv.korastratum.com/api/v1/idv"

For mobile SDK testing, use keys prefixed with kora_:

// Android
KoraIDV.configure(KoraIDVConfig(
    apiKey = "kora_abc123",
    tenantId = "your-tenant-uuid",
    environment = Environment.SANDBOX
))

// iOS
KoraIDV.configure(
    apiKey: "kora_abc123",
    tenantId: "your-tenant-uuid",
    environment: .sandbox
)

Test fixtures

Use specific externalId patterns when creating verifications to get deterministic results:

External ID pattern	Result	Use case
test-approve-*	Auto-approved with high score	Happy path testing
test-reject-*	Auto-rejected with low score	Rejection flow testing
test-fraud-*	Fraud alert + rejection	Fraud handling testing
test-review-*	Sent to manual review	Review queue testing
test-expired-*	Approved, then expires	Expiration handling
test-slow-*	Approved after 10s delay	Async/timeout testing

Example

# This verification will always be auto-approved
curl -X POST "$KORAIDV_BASE_URL/verifications" \
  -H "Authorization: Bearer kora_abc123" \
  -H "X-Tenant-ID: $KORAIDV_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "test-approve-user1", "tier": "standard"}'

Sandbox behavior

In sandbox mode:

• Document upload — Accepts any image (no real OCR or authenticity checking). Returns fixture scores.
• Selfie upload — Accepts any image. Returns a fixture face match score.
• Liveness — Accepts any challenge response. Returns a fixture liveness score.
• Complete — Returns the deterministic result based on the externalId pattern.
• Webhooks — Delivered normally to your configured endpoint with the same payload format as production, except every sandbox webhook payload additionally carries a "sandbox": true field so you can distinguish sandbox events.
• Image persistence — Images are stored and retrievable via the same API, but stored in a separate sandbox bucket.

Fixture responses

Auto-approve (test-approve-*)

{
  "status": "verified",
  "decision": "auto_approve",
  "decisionReason": "All checks passed",
  "scores": {
    "overall": 96.3,
    "documentQuality": 95.0,
    "documentAuth": 97.5,
    "faceMatch": 98.1,
    "liveness": 94.5
  }
}

Auto-reject (test-reject-*)

{
  "status": "rejected",
  "decision": "auto_reject",
  "decisionReason": "Document tampering detected",
  "scores": {
    "overall": 35.0,
    "documentQuality": 40.0,
    "documentAuth": 25.0,
    "faceMatch": 45.0,
    "liveness": 30.0
  }
}

Fraud alert (test-fraud-*)

Creates a fraud alert with severity: "critical" and alertType: "document_tampered", then rejects the verification.

Manual review (test-review-*)

{
  "status": "manual_review",
  "decision": "manual_review",
  "decisionReason": "Borderline score requires human review",
  "scores": {
    "overall": 65.0,
    "documentQuality": 70.0,
    "documentAuth": 60.0,
    "faceMatch": 72.0,
    "liveness": 58.0
  }
}

Testing webhooks locally

Use a tunneling service to receive webhooks on your local machine:

# Using ngrok
ngrok http 3000

# Use the generated URL as your callbackUrl
curl -X POST "$KORAIDV_BASE_URL/verifications" \
  -H "Authorization: Bearer kora_abc123" \
  -H "X-Tenant-ID: $KORAIDV_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "test-approve-webhook-test",
    "tier": "standard",
    "callbackUrl": "https://abc123.ngrok.io/webhooks/koraidv"
  }'

Sandbox limitations

• Sandbox verifications do not count toward your monthly quota
• Rate limits are the same as production (per your tier)
• Sandbox data is isolated from production — you cannot access sandbox verifications with a production key
• Image signed URLs in sandbox expire after 15 minutes, same as production