Credentials API Overview

What is the Credentials API?

The Beltic Credentials API issues cryptographically signed verifiable credentials that prove a fact about a subject — a business has been KYB’d, a user is over 21, an AI agent is authorized to spend up to $500 on behalf of its owner. Credentials are signed JWT-VCs (W3C Verifiable Credentials 2.0) that any verifier can validate against Beltic’s public keys without ever calling back to your servers. Use cases include:

Letting an authorized agent transact on a customer’s behalf without sharing payment credentials.
Proving to a counterparty that a business has been verified, without revealing the underlying KYB data.
Onboarding flows where a user’s identity check is reusable across services.

Core Concepts

Credential Types

Four discriminator-gated shapes: business, user, agent_authorization, and outcome_attestation. Each enforces its own claims schema at the API boundary.

Subject

The entity the credential is about — an organisation, person, agent, or document. The subject ID becomes part of the credential and is what verifiers index against.

Issuance

Beltic signs every credential with an ES256 key managed in AWS KMS. The signing key is published at /.well-known/jwks.json; any verifier can resolve it.

Revocation

Credentials are revocable via Status List 2021. Each credential is assigned a bit in your organisation’s bitstring; revocation flips the bit, and verifiers detect it on their next check.

Credential Lifecycle

Issue

Call POST /v1/credentials with a credential_type, a subject, and a claims object. Beltic validates the payload against the type-specific schema, allocates a status-list slot, signs the credential, and returns both the persisted record and the signed JWT-VC.

Verify

Anyone — your service, a partner, an external counterparty — can call POST /v1/credentials/verify with the JWT to confirm it’s valid, unexpired, and not revoked. The verify pipeline runs a seven-step check that includes signature verification against the issuer’s JWKS, claim validation, and a Status List 2021 lookup.

Revoke

Call POST /v1/credentials/{id}/revoke to mark a credential revoked. The credential’s bit in the org bitstring is flipped; verifiers see the revocation on their next status-list fetch (Cache-Control max-age 60s).

Audit

Every issue, verify, revoke, and delete writes an immutable audit event. Query the audit log via GET /v1/audit/events, or subscribe to webhook streams to react to events as they happen.

Authentication

All endpoints (except the public /.well-known/* paths and the public verify) require an API key passed as X-Api-Key. Keys are scoped by environment (sk_staging_* or sk_production_*) and carry a fixed set of permissions:

Permission	Required for
`credentials:write`	Issue (`POST /v1/credentials`, `POST /v1/credentials/batch-issue`)
`credentials:read`	List, get
`credentials:verify`	Verify
`credentials:revoke`	Revoke
`credentials:delete`	Delete

API keys are created in the Beltic Console. The raw key value is shown once at creation and never recoverable — store it securely.

Flat JSON Responses

The Credentials API returns flat JSON, not JSON:API. Resources come back with their fields at the top level:

{
  "id": "cred_01HQXYZ...",
  "credential_id": "cred_01HQXYZ...",
  "credential_type": "agent_authorization",
  "subject": {
    "id": "agent_widgetcorp_assistant",
    "type": "agent",
    "name": "WidgetCorp Customer Assistant"
  },
  "claims": {
    "permissions": [
      {
        "resource_type": "wallet",
        "resource_id": "*",
        "actions": ["payment_authorize", "checkout"],
        "conditions": [{ "field": "transaction_amount", "op": "lte", "value": 50000 }]
      }
    ]
  },
  "signed_payload": "eyJhbGciOiJFUzI1NiIs...",
  "status": "active",
  "issued_at": "2026-05-21T10:30:00Z",
  "expires_at": "2026-08-19T10:30:00Z"
}

This is intentional — the API is designed for direct integration without an SDK and without per-language JSON:API parsers.

Where to Next

Issue a Credential

Walk through POST /v1/credentials end-to-end, including credential-type-specific payloads.

Verify a Credential

Verify a JWT-VC and understand the seven-step verify pipeline.

Revoke a Credential

Revoke a credential and learn how the change propagates to verifiers.

Batch Issue

Issue thousands of credentials in a single async job.

Documentation Index

​What is the Credentials API?

​Core Concepts