API Reference

Authentication

REST v1 and SCIM requests require an organization API key. Generate one under Developer → API Keys in your issuer dashboard. Public credential, DID, status-list and OpenAPI endpoints do not require a key.

Authorization: Bearer cv_live_<your_api_key>

Keys are bound to one organization, with scopes, expiry and revocation. Use a separate key for each integration and grant only the scopes it needs. Passing an organization ID in a request does not change its authority.

REST API

Base URL: https://www.credverse.live/api/v1

Send JSON with Content-Type: application/json. Bodies are limited to 64 KiB; unknown properties and invalid UUIDs, emails and dates are rejected. Lists accept limit (1–100, default 50) and offset (0–1,000,000), and return {data, pagination: {limit, offset, hasMore}}. Credential lists also accept status and group_id. Pages can shift as new records arrive.

Issue a credential

Use a group in your organization. Omitted skills inherit the group defaults. Optional expiry_date is a future UTC YYYY-MM-DD; validity ends at its midnight. Store the returned credential ID and verification URL.

curl -X POST "https://www.credverse.live/api/v1/credentials" \
  -H "Authorization: Bearer $CREDVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: issue-jane-course-2026" \
  -d '{
    "group_id": "11111111-1111-4111-8111-111111111111",
    "holder_email": "recipient@example.com",
    "holder_name": "Jane Doe",
    "skills": ["Python", "AI"]
  }'

Success: 201 {id, verification_hash, verification_url, vc}, with Location and Idempotency-Replayed headers. Replace the example group UUID with your own.

Group creation accepts name, optional description (up to 4,000 characters), credential_type (certificate or badge) and up to 100 default_skills. Names are limited to 200 characters; each skill to 100. Webhook creation requires a URL and one or more event names (or * for all events). Analytics returns organization credential counts, group count and credit balance.

Endpoint reference

{
  "status": "revoked"
}

{
  "name": "Course completion",
  "description": "Completed the course",
  "credential_type": "certificate",
  "default_skills": [
    "Python"
  ]
}

{
  "url": "https://receiver.example.com/credverse",
  "events": [
    "credential.issued",
    "credential.revoked"
  ]
}

{
  "is_active": false
}

Webhooks

Receive HTTP POST notifications when credentials are issued, revoked, claimed, or expire. Configure webhooks from your dashboard under Developer → Webhooks, or via the REST API. Destinations must use public HTTPS on port 443. Private addresses and redirects are rejected.

Events are delivered at least once. Deduplicate by the authenticated event ID before side effects, and return 2xx only after accepting the work durably. Retries retain the original event ID and body, with up to five attempts and exponential delay. A failed delivery remains available for inspection. Creation responses include a signing secret, including identical idempotent replays; list/read responses omit it. Store the secret securely.

// Headers:
// X-CredVerse-Event: credential.issued
// X-CredVerse-Event-ID: <stable event UUID>
// X-CredVerse-Delivery-ID: <delivery UUID>
// X-CredVerse-Signature: t=<unix-seconds>,v1=<hex signature>
//
// Signed bytes: timestamp + "." + exact raw request body
// Expected signature: HMAC-SHA256(webhook_secret, signed bytes)
// Compare in constant time; reject timestamps outside a five-minute window.
// Do not parse and re-serialize JSON before verifying its signature.
// Body: {"id":"...","type":"credential.issued","timestamp":"...","data":{...}}

W3C Verifiable Credentials

New signed credentials use Ed25519 Data Integrity proofs with the eddsa-jcs-2022 cryptosuite. The proof covers the complete signed document. The verification endpoint returns that stored issuance snapshot; group edits and key rotation do not rewrite it. Historical public keys remain resolvable. Legacy proofs require an issuer signing upgrade before export.

curl "https://www.credverse.live/api/verify/$VERIFICATION_HASH" -H "Accept: application/ld+json"

A valid signature alone does not establish current validity. Verifiers must also check validUntil and the referenced revocation list, with an issuer they trust. Rotation preserves historical verification; compromised-key recovery requires revoking affected credentials and issuing replacements.

SCIM 2.0 User Provisioning

Provision issuer memberships with an organization API key containing scim:read and scim:write. Configure your identity provider's base URL as https://www.credverse.live/api/scim/v2 and use that key as its Bearer token. Test your IdP's configuration before enabling production synchronization.

This SCIM subset supports user lifecycle management, equality filters and ETags. It does not provide SAML/OIDC sign-in, groups, bulk operations, sorting or password changes. Global SCIM tokens are no longer accepted. Existing manually managed memberships and holder identities require explicit enrollment; they are not automatically adopted.

curl -X POST "https://www.credverse.live/api/scim/v2/Users" \
  -H "Authorization: Bearer $CREDVERSE_SCIM_KEY" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@example.com",
    "displayName": "Jane Doe",
    "externalId": "employee-123",
    "active": true
  }'

• List only this organization's SCIM-managed users. Use count (0–100), startIndex (1-based), or one equality filter, such as userName eq "jane@example.com". Other supported attributes are emails.value, externalId, id and active. Unsupported filters return an error.
• PATCH supports active, displayName, name.formattedand externalId. userName is immutable; returned emails reflect it.
• User responses include an ETag such as W/"2". Send it in If-Matchwhen updating; stale writes return 412 without changing the user. Conditional PUT/PATCH success returns 204 with the new ETag; GET the user for its updated representation. Updates without If-Match return 200 and the resource. Attribute projection on updates is unsupported.
• Deactivation or deletion removes only the membership provisioned by SCIM. It preserves the global identity and other organizations. Owners must transfer ownership before deprovisioning.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "jane@example.com",
  "displayName": "Jane Doe",
  "active": true
}