Discovery & Endpoints — Authkeep Docs

Required Endpoints

An SIG issuer identified by did:web:example.com must serve four resources at well-known HTTPS URLs:

Endpoint	URL
DID Document	`https://example.com/.well-known/did.json`
JWKS	`https://example.com/.well-known/jwks.json`
SIG Metadata	`https://example.com/.well-known/sig.json`
Event Feed	`https://example.com/.well-known/sig/events.jsonl`

All endpoints must be served over HTTPS with a valid TLS certificate. The domain in the URL must match the domain in the issuer’s did:web DID.

DID Document

The DID Document (did.json) binds the issuer’s DID to its signing keys and follows the W3C DID Core specification.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:example.com",
  "verificationMethod": [
    {
      "id": "did:web:example.com#orgsign-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:example.com",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "base64url-encoded-public-key"
      }
    }
  ],
  "assertionMethod": [
    "did:web:example.com#orgsign-1"
  ]
}

Key points:

Each verificationMethod entry uses type JsonWebKey2020 and embeds the public key as a JWK.
The assertionMethod array references the key IDs that are authorized to sign SIG events.
The fragment in the verification method id (e.g., #orgsign-1) should correspond to the kid used in JWS protected headers and JWKS entries.

JWKS

The JSON Web Key Set (jwks.json) publishes the issuer’s public signing keys in standard JWK format.

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url-encoded-public-key",
      "kid": "orgsign-1",
      "use": "sig",
      "alg": "EdDSA"
    }
  ]
}

Field	Value	Description
`kty`	`"OKP"`	Octet Key Pair — the key type for Ed25519
`crv`	`"Ed25519"`	The elliptic curve
`x`	base64url string	The public key bytes
`kid`	string	Key identifier, referenced by JWS `kid` headers
`use`	`"sig"`	Key is used for signatures
`alg`	`"EdDSA"`	The signing algorithm

The JWKS may contain multiple keys to support key rotation. Consumers resolve kid values from JWS headers against this set.

SIG Metadata

The SIG metadata document (sig.json) provides protocol-level configuration for consumers.

{
  "issuer": "did:web:example.com",
  "protocol_version": "0.1",
  "events_url": "/.well-known/sig/events.jsonl",
  "jwks_url": "/.well-known/jwks.json",
  "public_only": false
}

Field	Type	Description
`issuer`	string	The issuer’s `did:web` DID
`protocol_version`	string	SIG protocol version (currently `"0.1"`)
`events_url`	string	Relative or absolute URL to the event feed
`jwks_url`	string	Relative or absolute URL to the JWKS
`public_only`	boolean	Whether the feed contains only public-visibility events

The events_url and jwks_url fields allow flexibility in deployment. They may be relative paths (resolved against the issuer’s origin) or absolute URLs.

Event Feed

The event feed (events.jsonl) is a newline-delimited JSON (NDJSON) file. Each line is a complete JWS JSON Flattened Serialization object containing a signed SIG event.

{"protected":"eyJ...","payload":"eyJ...","signature":"abc..."}
{"protected":"eyJ...","payload":"eyJ...","signature":"def..."}
{"protected":"eyJ...","payload":"eyJ...","signature":"ghi..."}

Requirements:

Each line is a valid JSON object with protected, payload, and signature fields.
Events appear in ascending sequence order (sequence 1 on line 1, sequence 2 on line 2, etc.).
The file is append-only. Existing lines must never be modified or removed.
The file must be served with Content-Type: application/x-ndjson or application/jsonl.
Consumers stream the file line-by-line, verifying and reducing each event in order.

Discovery Flow

A consumer discovering an issuer’s relationships follows this sequence:

Resolve did:web:example.com to https://example.com/.well-known/did.json per the did:web method specification.
Fetch the DID Document and extract assertionMethod key references.
Fetch https://example.com/.well-known/sig.json to get the event feed URL and JWKS URL.
Fetch the JWKS from jwks_url and index keys by kid.
Fetch and stream the event feed from events_url.
Verify each event using the 9-step verification procedure.
Replay verified events through the reducer to derive current relationship state.