Skip to main content

Core Concepts

Proof Requests​

The central object in Tokenive. A proof request represents a verification task: "I need this person to prove they have a valid passport."

Key fields:

  • requester_entity — your organization identifier
  • claim_type_id — what you're verifying (e.g., passport)
  • customer_email — the person being verified
  • status — current state of the verification

Providers​

A provider is a verification backend for a specific claim type. Each provider knows how to validate one type of credential using zkTLS proofs. Use client.providers.list() to see what's available.

API Keys​

API keys authenticate your backend with Tokenive. Keys follow the format tok_live_... and are scoped to a tenant with specific permissions.

  • Create keys via client.apiKeys.create()
  • Revoke compromised keys via client.apiKeys.revoke(id)
  • Keys track last_used_at for auditing

DIDs (Decentralized Identifiers)​

Holders are identified by DIDs — self-sovereign identifiers that let them prove ownership of credentials. When a holder claims a proof request, their DID is bound to it.

Tenants​

Each institution operates within a tenant. API keys, proof requests, and permissions are scoped to a tenant. Your API key determines which tenant you're operating in.

Idempotency​

The SDK supports idempotency keys on proof request creation to safely retry requests without creating duplicates:

await client.proofRequests.create({
  requester_entity: 'my-org',
  claim_type_id: 'passport',
  customer_email: 'user@example.com',
  idempotencyKey: 'unique-request-id-123',
});