Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.beltic.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Beltic publishes three .well-known endpoints that any verifier — your own service, a counterparty, an offline tool — can fetch without authentication. These are the building blocks of W3C-compliant verifiable credentials: the JWKS exposes the signing keys, the DID document describes the issuer identity, and the status list reports revocations.

​
/.well-known/jwks.json

Returns the issuer’s JSON Web Key Set: the public keys credentials are signed with. Verifiers fetch this to validate signatures. 
curl https://api.beltic.com/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "K8L9...",
      "x": "...",
      "y": "...",
      "alg": "ES256",
      "use": "sig"
    }
  ]
}
  • The kid matches the kid claim in every JWT-VC’s header.
  • V1 publishes a single signing key; multi-key rotation lands in a later phase.
  • Cache-Control is 1 hour. Verifiers should respect it.

​
/.well-known/did.json

Returns the W3C DID document for did:web:beltic.com. The DID document describes the issuer identity and references the JWKS endpoint. 
curl https://api.beltic.com/.well-known/did.json

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:beltic.com",
  "verificationMethod": [
    {
      "id": "did:web:beltic.com#K8L9...",
      "type": "JsonWebKey2020",
      "controller": "did:web:beltic.com",
      "publicKeyJwk": { /* same key as in jwks.json */ }
    }
  ],
  "assertionMethod": ["did:web:beltic.com#K8L9..."]
}
Use this when integrating with verifiers that resolve issuers via DID rather than direct JWKS fetch — most W3C-conformant verifier libraries do.

​
/.well-known/status-lists/v1

Returns the Status List 2021 bitstring for the org whose credentials are being verified. The bit at status_list_index is 1 for revoked credentials, 0 for active. 
curl https://api.beltic.com/.well-known/status-lists/v1?org=org_01HQ...

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/vc/status-list/2021/v1"
  ],
  "id": "https://api.beltic.com/.well-known/status-lists/v1?org=org_01HQ...",
  "type": ["VerifiableCredential", "StatusList2021Credential"],
  "issuer": "did:web:beltic.com",
  "credentialSubject": {
    "id": "https://api.beltic.com/.well-known/status-lists/v1?org=org_01HQ...#list",
    "type": "StatusList2021",
    "statusPurpose": "revocation",
    "encodedList": "H4sIAAAAA..."
  }
}
  • encodedList is a base64url-encoded, gzipped byte-aligned bitstring. Decode, gunzip, then check bit status_list_index MSB-first within each byte.
  • Cache-Control is 60 seconds — short enough that revocations propagate quickly, long enough that high-throughput verifiers don’t hammer the endpoint.
  • The org query parameter targets a specific organisation’s bitstring. Each org has its own.

​
Decoding the Bitstring

// Pseudocode for checking bit `index` in encodedList
const compressed = base64urlDecode(encodedList);
const bytes = gunzip(compressed);
const byteIdx = Math.floor(index / 8);
const bitOffset = 7 - (index % 8);
const isRevoked = (bytes[byteIdx] & (1 << bitOffset)) !== 0;

​
When to Use Which

You want to…Fetch
Verify a JWT signature offline/.well-known/jwks.json
Integrate with a W3C-conformant verifier library/.well-known/did.json
Check whether a specific credential has been revoked/.well-known/status-lists/v1?org=...
Run the full verify pipeline server-sidePOST /v1/credentials/verify (handles all three for you)

​
Caching Recommendations

  • JWKS: cache for 1 hour. Re-fetch only on kid mismatch.
  • DID document: cache for 1 hour. Treat it as the same lifetime as JWKS.
  • Status list: cache for 60 seconds. If your application can tolerate longer staleness, increase locally — but understand that revocations won’t propagate faster than your cache TTL.