> ## 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.

# Public Endpoints (.well-known)

> JWKS, DID document, and Status List 2021 bitstring — the public endpoints verifiers fetch to validate credentials.

## 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.

```bash theme={null}
curl https://api.beltic.com/.well-known/jwks.json
```

```json theme={null}
{
  "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.

```bash theme={null}
curl https://api.beltic.com/.well-known/did.json
```

```json theme={null}
{
  "@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.

```bash theme={null}
curl https://api.beltic.com/.well-known/status-lists/v1?org=org_01HQ...
```

```json theme={null}
{
  "@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

```ts theme={null}
// 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.