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.

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, 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-v1 profile and spec §5.

v0.2 specifies that Delegus 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.

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 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). Later, anyone holding the receipt can re-run the open checks against the preserved artifacts (spec §8) and reach the same result without calling Delegus.

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.2 specifies either a managed did:web:delegus.ai:rp:<slug> or your own did:web (spec §2.3). Nothing about it touches the hot path; the API key resolves to it.

If you are the company issuing Grants#

The other side of the protocol is the Principal: the company whose agent acts. v0.2 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). The SDK's delegus.org.create(), agent.create() and grant.create() cover that path (spec §15).

Try it against the sandbox#

This runs the real verify path in a sandbox, with a sandbox company and agent that exist only there. The receipts are real; the identities are not production ones (spec §2.0 keeps them apart). No key leaves the server: the sandbox verifies as its own relying party.

Read next#

• The specification, v0.2, frozen with errata 1 and 2 applied.
• The delegus-base-v1 profile, the normative check table whose hash every receipt carries.
• Machine-readable overview for agents and language models.