Public Endpoints (.well-known)

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-side	`POST /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.

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

Public Endpoints (.well-known)

Overview

`/.well-known/jwks.json`

`/.well-known/did.json`

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

Decoding the Bitstring

When to Use Which

Caching Recommendations

​Overview

​/.well-known/jwks.json

​/.well-known/did.json

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

​Decoding the Bitstring

​When to Use Which

​Caching Recommendations

Overview

`/.well-known/jwks.json`

`/.well-known/did.json`

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

Decoding the Bitstring

When to Use Which

Caching Recommendations