DelegusDocsv0.3 rc1

Docs/Quickstart

Getting started

Quickstart: your first signed decision

Sign up, copy your verify key, send one request, and keep the signed receipt that comes back. The sandbox is free, with no card. To go live later, you verify your company's domain.

Signup to first signed receipt: under a minute.

The person who gives an agent its authority stays in charge of it. They decide what it may do, one revoke takes it back everywhere, and every decision comes with a signed receipt.

1. Sign up#

  1. Go to app.delegus.ai, enter your Work email and choose Email me a link. There's no password.
  2. Open the email ("Sign in to the Delegus console"). The link works for 15 minutes. It opens a page that asks you to confirm; choose Sign me in.
  3. Name your organization and choose Create organization. You become its first admin.

New organizations start on v0.3 of the protocol (the delegus-base-v3 profile).

Use your work email if you can. A free email address (Gmail, Outlook, iCloud and similar) works for the sandbox, but it cannot verify a company domain, so that organization stays on the sandbox.

2. Copy your verify key#

The next screen, "your organization is ready", shows a verify key for your server. It starts with dk_rp_.

Put it in your server's environment, never in your code:

bash
export DELEGUS_API_KEY=dk_rp_...

3. Send the sample request#

Open Getting started in the console (app.delegus.ai/getting-started). It shows a sample Grant and Proof you can use straight away. The sample Grant lasts one hour and each sample Proof five minutes; reload the page for fresh ones. If you would rather not run anything yet, choose See my first receipt and the console sends the request for you.

With curl, paste the sample Grant and Proof in place of the placeholders:

bash
curl -s https://api.delegus.ai/verify \
  -H "authorization: Bearer $DELEGUS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"grant":"<JWS>","proof":"<JWS>","action":{"type":"commerce:purchase","resource":"sandbox/quickstart","amount":1000,"currency":"USD"}}'

amount is in minor units, so 1000 is $10.00.

Or with the SDK (npm install @delegus/sdk):

ts
import { Delegus } from "@delegus/sdk";

const delegus = new Delegus({ apiKey: process.env.DELEGUS_API_KEY });
const d = await delegus.verify({ grant, proof, action });
console.log(d.decision); // "ALLOW"; d.receipt is the signed receipt to keep

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 verify key from sign-up belongs to a relying party that Delegus hosts for you, so it needs no domain proof. If you register a relying party on your own domain instead (for example did:web:computeco.example), /verify answers HTTP 403 RP_UNVERIFIED, with no receipt, until that domain is verified. See Verify your domain.

4. Your first signed ALLOW#

The answer is HTTP 200 with the decision and a signed receipt:

json
{
  "decision": "ALLOW",
  "reason": null,
  "receipt_id": "drc_...",
  "receipt": "eyJ... (a signed compact JWS)"
}

That is a trimmed view; the full response is in the API reference. On v0.3 the response also carries, beside the receipt, the matched authority in plain form and the values needed to check it against the receipt; the SDK checks them for you. 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 receipt. It records the decision: which Grant was checked, against what, and what Delegus Check decided. Anyone holding it can check offline, without calling Delegus, that it is authentic and unchanged. A refusal comes back the same way: "decision": "DENY" with a reason code and its own signed receipt. Every reason code is in DENY reason codes.

5. Give your agent authority#

So far you've checked a sample grant. To let your own agent act, your company gives it authority in a signed grant. There are two ways.

bash
delegus keygen --out ./company.jwk
delegus org create --slug <name> --key ./company.jwk
delegus grant compile --sentence "Let ordering-agent pay acme-* up to $250 per day until 2026-12-31" --agents ./agents.json
delegus grant create --key ./company.jwk --kid <key id> --agent <agent did:key> --authority ./authority.json

org create registers your key once (with your account's admin key in DELEGUS_API_KEY; see the two-command setup). grant compile turns the sentence into the exact capabilities and reads them back in plain words; pass those capabilities to grant create as --authority. See what you can write for the sentence forms both understand.

Either way, your agent sends the grant with each request, and the business it's dealing with checks it the way you just did.

Free to start#

The sandbox is free, with no card, and uses test Grants only. When you go live, you add a card and the first 14 days in production are free; on day 15 you move to Starter at $99 a month unless you cancel. Going live needs a verified domain: verify your domain first, signed in with your work email at that domain. The console's Usage page shows how many you have used this month.

Next#