API reference
Discovery
The two unauthenticated documents every operator publishes — its configuration and its signing keys.
Both are public and take no credential. Anyone considering an integration must be able to read them before there is a relationship to authenticate.
GET /.well-known/path-configuration
See Discovery for the full document and field-by-field notes. The short version of what to do with it:
const config = await path.discovery();
// Can this operator do what you need?
config.conformance.includes('PATH-REQ.Link');
// Which version to pin.
config.api_version_latest;
// The part to read before joining a network.
config.finder.hashing; // "server_side" → the network sees searched identifiers
config.finder.sonar_mode; // "central" | "broadcast"finder.hashing is the material field for anyone evaluating a network. server_side means
identifiers are visible to the network operator in the course of a search. That is an honest
declaration of a real exposure, not a defect to route around. See Privacy.
Caching
Cache it, with roughly an hour as a sensible default. Refetch when an envelope arrives with an
unknown kid — that is the signature of a key rotation you have not picked up, and it is a
different problem from a bad signature.
GET /.well-known/path-keys
{
"keys": [
{
"kid": "op_example_2026_01",
"kty": "OKP",
"crv": "Ed25519",
"alg": "EdDSA",
"use": "sig",
"public_key_hex": "d75a980182b10ab7d54bfed3c964073a…"
}
]
}Verifying with it
import { verifyAgainstIssuer } from '@pathprotocol/sdk';
const { valid, reason } = await verifyAgainstIssuer(envelope, 'https://api.example.com');Read the kid from the envelope; fetch the key from the issuer's own document.
Never from whoever served the envelope, and never from a central registry. An operator vouching for another operator's key rebuilds the trust hierarchy this design exists to avoid — and it means a compromise of one operator compromises statements about others.
Rotation
Publish, then switch. The new key appears alongside the old; new envelopes carry the new kid; old
envelopes stay verifiable because their key is still listed. Retire a key only once nothing in
circulation still references it.
An unknown kid should be reported as such rather than as a bad signature — the two mean very
different things, and conflating them turns a routine rotation into a support incident.