Integrate Delegus as a relying party

What arrives with the request#

An agent acting for a company sends two extra headers with its HTTP request:

You do not parse either. You forward them, together with your own description of the action, to Delegus.

Install#

npm install @delegus/sdk

The SDK bundles the CLI (npx delegus) and pulls in the pure engine @delegus/core. Both are Apache-2.0.

Use @delegus/sdk 0.2.0 or later: it is the first release that carries v0.3 (protocol: "v0.3", the opening and commitment checks, and "auto" as the default). 0.1.4 has none of it.

The one call#

This is the complete relying-party integration as spec §15 gives it:

import { Delegus } from "@delegus/sdk";
const delegus = new Delegus({ apiKey: process.env.DELEGUS_API_KEY, publicBaseUrl: "https://seller.example" });

app.post("/orders", async (req, res) => {
  const d = await delegus.verify({
    grant: req.header("Delegus-Grant"),
    proof: req.header("Delegus-Proof"),
    action: { type: "commerce:purchase", resource: req.body.orderId, amount: req.body.amountMinor, currency: req.body.currency },
    request: { method: req.method, path: req.path },
  });
  if (d.decision !== "ALLOW") return res.status(403).json({ reason: d.reason });
  // proceed; persist d.receipt with the order
});

The Proof carries the method and URL the agent signed for (spec §4). /verify doesn't compare them with your request; the SDK does, before it calls Delegus Check, when you pass request, and throws ProofBindingError on a mismatch. publicBaseUrl is the origin the agent addressed; the SDK joins request.path to it. amount is an integer in minor units; the protocol never uses decimals.

What comes back#

decision is ALLOW or DENY. On DENY, reason is the first check that failed, in the fixed order the profile document lays down, for example GRANT_EXPIRED, AUTHORITY_REVOKED, PROOF_REPLAYED or AMOUNT_EXCEEDS_AUTHORITY. The full list and its order are in the delegus-base-v3 profile and spec §5. The profile is published at /profiles/delegus-base-v3.

v0.3 specifies that Delegus Check fails closed: an unknown, missing, ambiguous or unavailable input is a DENY, never an ALLOW. If Delegus itself cannot answer, the SDK surfaces SERVICE_UNAVAILABLE, and your service decides what to do with a request it could not verify.

Some answers come back before any check runs. They're refusals rather than decisions, so there's no receipt, and the agent's Proof isn't spent; the same Proof works once the cause is fixed. The SDK throws them as DelegusApiError with the HTTP status and the code.

On v0.3 the response also carries, beside the receipt and outside its signature, the matched authority in plain form and the values that tie it to the receipt. The SDK checks that they match what the receipt pins and throws ResponseIntegrityError if they do not; do not act on such a response. The fields are authority (the authority that matched), authority_opening and, for a Grant with a budget, capability_key_opening; the receipt pins them as authority_commitment and evidence.consumption.capability_key_commitment (spec §5.6, §6.2).

Keep the receipt#

Every decision, ALLOW and DENY alike, comes with a signed Decision Receipt (spec §6). It pins hashes of the Grant, the request, the authority that matched, the company's DID document as it stood, the revocation list as it stood, the profile that was applied, and the evaluation time. Store it with the order. You can also list and search your decisions later with GET /decisions (newest first, filters by time, decision, reason, Principal or Grant). Anyone holding the receipt can check that it is authentic and unchanged without calling Delegus. Checking what it pins against the preserved artifacts (spec §8) is open to the receipt's relying party and Principal; re-evaluating the checks themselves offline is not available yet.

Before you can call it#

• An API key for your relying party. Sign up at app.delegus.ai and copy your verify key.
• First check. With your key in DELEGUS_API_KEY, run delegus doctor: it confirms the API is reachable, the backing services are healthy, the service DID document resolves, your key is valid, and prints your settings. Exit code 0 means go; 2 tells you what is wrong. Then delegus key list, key create and key revoke handle rotation from the shell.
• Key hygiene. Rotate a key with POST /api-keys (it returns a new key once), then POST /api-keys/{key_id}/revoke on the old id; a revoked key stops working immediately. Any live key of the same relying party or Principal can do this, so a leaked key never has to wait for us.
• Your relying-party identity. v0.3 specifies either a managed did:web:delegus.ai:rp:<slug> or your own did:web (spec §2.3). A managed identity works as it is. Your own did:web, such as did:web:computeco.example, needs your organization to verify that domain first: you can register it once a claim is started, and /verify answers RP_UNVERIFIED until the claim is verified. Nothing about it touches the hot path; the API key resolves to it.
• Going live. Production checks need a verified domain for your organization, whichever identity your relying party uses. The sandbox does not.

If you are the company issuing Grants#

On the other side of the protocol is the Principal, the company whose agent acts. v0.3 specifies that it proves control of its domain (spec §2.1), signs Grants with a key in its DID document (spec §3), and can revoke a Grant at any moment (spec §7). A Principal on your own did:web is registered only after your organization has started a claim on that domain, and its Grants pass the domain check only while the claim is verified; see Verify your domain. The SDK's delegus.org.create(), agent.create() and grant.create() cover that path (spec §15).

The four outcomes, step by step#

Take one order from one agent and watch Delegus Check answer it four ways. You mint a Grant and a Proof, and the first verify comes back ALLOW. Send the same Proof again and it's PROOF_REPLAYED. Mint an order over the limit and it's AMOUNT_EXCEEDS_AUTHORITY. Revoke the Grant, verify the first pair again, and it's AUTHORITY_REVOKED.

That last one is why revocation is checked at P6, before the replay write at T5. A revoked Grant denies as revoked even when its Proof was already used. To run these steps yourself, get a free sandbox key and follow the quickstart.

Read next#

• Verify your domain: the steps, the daily re-check, and the errors.
• The specification, v0.3 release candidate. v0.2 stays the sole normative text until v0.3 is frozen.
• The delegus-base-v3 profile, the check table whose hash every receipt carries.
• Machine-readable overview for agents and language models.