API Documentation

Overview

Vercre is a credential issuance and verification infrastructure API for W3C verifiable credentials with on-chain attestation anchoring on Base (Ethereum L2). It provides:

• W3C Verifiable Credential Data Model v2.0 compliance
• Custodial key management (private keys encrypted at rest, never exposed)
• Multi-algorithm support (Ed25519, secp256k1)
• Three DID methods (did:key, did:ethr, did:web)
• On-chain attestation anchoring for public verifiability
• Four-tier issuer trust registry with staking and reputation
• Usage-based billing via Stripe

Base URL

All API requests should be made to:

All request and response bodies use camelCase JSON.

Authentication

Most endpoints require an API key passed in the X-API-Key header. Keys use the format:

vercre_client_<32-hex>   (CLIENT role)
vercre_admin_<32-hex>    (ADMIN role)
vercre_platform_<32-hex> (PLATFORM_ADMIN role)

Include the header in all authenticated requests:

X-API-Key: vercre_admin_your_key_here

Roles & Permissions

Quickstart

Get up and running in 3 steps:

1. Install the SDK

pip install vercre-sdk

2. Onboard (get your API key)

curl -X POST https://vercre.vectorguardlabs.com/api/v1/onboard \
  -H "Content-Type: application/json" \
  -d '{"name":"Your Organization Name"}'

3. Issue your first credential

curl -X POST https://vercre.vectorguardlabs.com/api/v1/issue \
  -H "X-API-Key: vercre_admin_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerDid": "did:key:z6MkYourDID",
    "subjectDid": "did:key:z6MkSubjectDID",
    "credentialType": "KYCBasicCredential",
    "claims": {
      "kycLevel": "basic",
      "countryOfResidence": "US",
      "verificationMethod": "document",
      "verifiedAt": "2025-01-01T00:00:00Z"
    },
    "expiration": "2026-01-01T00:00:00+00:00"
  }'

Unauthenticated Endpoints

These endpoints require no API key.

Health Check

curl https://vercre.vectorguardlabs.com/api/v1/health

Response:

{"status": "ok", "version": "1.0.0"}

Onboarding

curl -X POST https://vercre.vectorguardlabs.com/api/v1/onboard \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}'

Response includes: did, name, tier (UNVERIFIED), status, reputation, stake, publicKey, apiKey, apiKeyId

Client / Admin Endpoints

Requires a CLIENT or ADMIN API key.

Admin Endpoints

Requires an ADMIN or PLATFORM_ADMIN API key.

Platform Admin Endpoints

Requires a PLATFORM_ADMIN API key.

Credential Types

The API supports five credential types with tiered schemas. Claim keys use camelCase (W3C convention).

KYC Credentials (Tiered)

Other Credentials

Issuing Credentials

POST /api/v1/issue

Issue a credential and anchor its hash on-chain. The signing key is looked up server-side by the issuer DID.

Request Body

{
  "issuerDid": "did:key:z6MkIssuer",
  "subjectDid": "did:key:z6MkSubject",
  "credentialType": "KYCBasicCredential",
  "claims": {
    "kycLevel": "basic",
    "countryOfResidence": "US",
    "verificationMethod": "document",
    "verifiedAt": "2025-01-01T00:00:00Z"
  },
  "expiration": "2026-01-01T00:00:00+00:00"
}

Optional Fields

Add issuer metadata and schema version:

{
  "issuerDid": "did:key:z6MkIssuer",
  "subjectDid": "did:key:z6MkSubject",
  "credentialType": "AMLScreeningCredential",
  "claims": {
    "sanctionsStatus": "clear",
    "pepStatus": false,
    "adverseMedia": false,
    "riskScore": 10,
    "screenedAt": "2025-01-01T00:00:00Z"
  },
  "schemaVersion": "1.0.0",
  "issuerName": "Acme Compliance",
  "issuerJurisdiction": "US-SEC",
  "issuerLicense": "LIC-001"
}

Verifying Credentials

POST /api/v1/verify

Verify a credential's JWT signature and on-chain attestation status. Optionally apply policy constraints.

Basic Verification

curl -X POST https://vercre.vectorguardlabs.com/api/v1/verify \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credential": {...}}'

Verification with Policy

curl -X POST https://vercre.vectorguardlabs.com/api/v1/verify \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {...},
    "policy": {
      "minTier": "REGULATED",
      "minReputation": 60
    }
  }'

Response Fields

The response includes a confidence score (0.0-1.0) weighted across three dimensions:

• Credential validity (40%) — signature valid, not expired, not revoked
• Issuer tier (30%) — higher tier = higher confidence
• Issuer reputation (30%) — reputation score mapping

The response also includes a freshness heuristic:

Revoking Credentials

POST /api/v1/credentials/revoke

Revoke an on-chain attestation. Only the original issuer can revoke their own credentials.

curl -X POST https://vercre.vectorguardlabs.com/api/v1/credentials/revoke \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {...},
    "issuerDid": "did:key:z6MkIssuer"
  }'

Credential Renewal

POST /api/v1/credentials/renew

Renew a credential in a single API call. The old credential is revoked and a new one is issued with the same claims but a new expiration.

curl -X POST https://vercre.vectorguardlabs.com/api/v1/credentials/renew \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {...},
    "issuerDid": "did:key:z6MkIssuer",
    "newExpiration": "2027-06-01T00:00:00Z"
  }'

Issuer Trust Tiers

Issuers are classified into four tiers that control which credential types they may issue:

Operational Status

Tiers are separate from operational status. An issuer has both a tier and a status:

Reputation Scoring

Every issuer starts with a base score of 50 (range 0–100). Events adjust the score:

DID Methods

The API supports three Decentralized Identifier methods:

Key Types

Key Rotation

Signing keys can be rotated without invalidating existing credentials. Old keys are preserved so previously-signed credentials remain verifiable.

Rotate a Key

POST /api/v1/keys/{did}/rotate

curl -X POST https://vercre.vectorguardlabs.com/api/v1/keys/did:key:z6MkIssuer/rotate \
  -H "X-API-Key: $ADMIN_KEY"

Response: message, did, newPublicKey, keyType

List Key Versions

GET /api/v1/keys/{did}/versions

curl https://vercre.vectorguardlabs.com/api/v1/keys/did:key:z6MkIssuer/versions \
  -H "X-API-Key: $ADMIN_KEY"

Response: array of {version, active, publicKey, keyType, createdAt, rotatedAt}

Issuer Verification Flow

Onboarding creates an issuer at the UNVERIFIED tier. To move to a higher tier, submit a verification request declaring your target tier with required documentation.

Flow

1. Onboard: POST /api/v1/onboard → UNVERIFIED + ADMIN key
2. Submit request: POST /api/v1/issuers/{did}/verify-request → declares target tier + required fields
3. Platform admin approves: POST /api/v1/issuers/{did}/approve → validates data, sets tier

Per-Tier Requirements (Cumulative)

Example: Submit Verification Request

curl -X POST https://vercre.vectorguardlabs.com/api/v1/issuers/did:key:z6Mk.../verify-request \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedTier": "VERIFIED",
    "entityType": "bank",
    "jurisdiction": "US",
    "licenseId": "FDIC-12345",
    "website": "https://acmecorp.com"
  }'

Webhooks

Register webhook endpoints to receive real-time HTTP POST notifications when events occur. Webhooks are scoped to the registering issuer's DID.

Event Types

Register a Webhook

curl -X POST https://vercre.vectorguardlabs.com/api/v1/webhooks \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hook",
    "events": ["verification.passed", "verification.failed", "credential.revoked"]
  }'

Retry Policy

Webhook dispatch uses exponential backoff:

HTTP 4xx responses are treated as terminal (no retry). Maximum 10 webhooks per issuer.

Rate Limiting

Rate limits are applied to sensitive endpoints using a Redis-backed sliding window algorithm:

When exceeded, returns 429 Too Many Requests with Retry-After header.

Billing & Plans

Usage-based billing is integrated via Stripe with six plans:

Issuer Plans

Verifier Plans

Billing Endpoints

On-Chain Anchoring

Paid-tier issuers can anchor credential hashes on the production AttestationRegistry smart contract on Base (Ethereum L2). This makes credentials publicly verifiable by any third party on BaseScan.

How It Works

1. Credential is issued and signed as a JWT
2. SHA-256 hash of the credential is computed (deterministic canonical JSON)
3. Hash is anchored on-chain with optional expiration
4. Any verifier can check attestation status via the contract (public read, no API key needed)

Attestation States

Authorize On-Chain (One-Time)

curl -X POST https://vercre.vectorguardlabs.com/api/v1/chain/authorize \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"issuerDid": "did:key:z6MkYourDID"}'

SD-JWT (Selective Disclosure)

The SDK supports SD-JWT for privacy-preserving credential presentation. Issuers create JWTs with selectively disclosable claims, and holders reveal only what verifiers need.

How It Works

1. Issuer creates an SD-JWT marking which claims are selectively disclosable
2. Holder presents only the claims the verifier requires (with key binding proof)
3. Verifier verifies the signature and reconstructs only the disclosed claims

Example (Python SDK)

from vercre.crypto.sd_jwt import create_sd_jwt, present_sd_jwt, verify_sd_jwt

# Issuer: create SD-JWT with selectively disclosable claims
sd_jwt, disclosures = create_sd_jwt(
    payload={"iss": issuer_did, "sub": holder_did,
             "name": "Alice", "age": 30, "country": "US"},
    key_pair=issuer_kp,
    sd_claims=["name", "age", "country"],
    holder_did=holder_did,
)

# Holder: present only "age" (with key binding proof)
presentation = present_sd_jwt(
    sd_jwt, disclosures, ["age"],
    holder_key_pair=holder_kp,
    audience="verifier.example.com",
    nonce="challenge123",
)

# Verifier: verify and reconstruct only disclosed claims
claims = verify_sd_jwt(
    presentation, issuer_kp.public_key_bytes, KeyType.ED25519,
    holder_public_key_bytes=holder_kp.public_key_bytes,
    holder_key_type=KeyType.ED25519,
    expected_audience="verifier.example.com",
    expected_nonce="challenge123",
)
# claims = {"iss": "...", "sub": "...", "age": 30}
# "name" and "country" are NOT revealed

Error Handling

The API uses standard HTTP status codes. Error responses include a detail field with a human-readable message.

Example Error Response

{
  "detail": "Rate limit exceeded. Try again in 3600 seconds."
}

Common Troubleshooting

• 429 on onboarding: Wait 1 hour (3 requests/hour per IP)
• 403 "API key must be bound to a DID": Create a CLIENT key with DID binding to file disputes
• 403 "not authorized for this issuer DID": Use the ADMIN key from onboarding for that specific issuer
• 422 self-issuance: Issuer DID and subject DID must be different

SDK Installation

Install the Python SDK from PyPI:

# Core SDK
pip install vercre-sdk

# With EVM (on-chain) integration
pip install "vercre-sdk[evm]"

# With YugabyteDB backend
pip install "vercre-sdk[pg]"

# With OpenTelemetry tracing
pip install "vercre-sdk[tracing]"

# All production features
pip install "vercre-sdk[evm,pg,tracing]"

Requirements

• Python 3.13+
• uv (recommended) or pip

Self-Hosted Server

Run your own instance with full SDK functionality (file-backed attestation):

pip install vercre-sdk
vercre-server  # Starts on 0.0.0.0:8000

Links

• PyPI Package
• Product Website