Approve grants with a passkey

Owning your own key stays fully supported. You can use either way, or both on the same identity.

What Delegus holds, and what it can never do#

When you choose this, Delegus creates an Ed25519 signing key for your company inside AWS KMS. The private key is generated there and never leaves it. Its public half is published in your identity's DID document, so anyone can check what it signs.

Delegus asks KMS to sign only after it has checked a passkey approval over the exact bytes of the grant. Nothing else can make it sign: not an API key, not a console session, and not Delegus staff.

Keys are only ever added, never deleted. In production, an organization-wide lock stops anyone deleting or disabling them, and only the API may sign with them.

Delegus never receives a fingerprint, face data, a PIN or any other way your device unlocks. Those stay on the device. A passkey sends only a signature and the flags saying the device checked the person.

Who can use it#

It's for identities Delegus hosts for you, the ones named did:web:delegus.ai:org:<name>. If your company publishes its own DID document on its own domain, keep signing with your own key.

A hosted name proves no company name, so it can't use one. A name is refused if any of its words is the name of a domain another organization has verified, or a well-known brand.

Set it up#

1. In the console, open Give authority and choose Let Delegus hold a key. Pick a short name for your organization at Delegus.
2. Add your passkey. Your organization's first passkey is added by an admin. Each approver gives the name the approval record will show.
3. Add more approvers. Every passkey after the first needs an existing approver to vouch for it. They get a link that works for five minutes, and they confirm with their own passkey. That way a stolen console session can't add its own passkey and start approving. An admin can disable an approver at any time; from then on their passkeys can't approve or vouch for anyone. An admin can also remove an approver for good, which revokes every passkey they have, or revoke just one passkey when a device is lost; the person stays an approver with their other passkeys.

Name your agents#

Grants are written to an agent's key, a long did:key:z6Mk… identifier. On the console's Agents page you give each agent a short name instead, like ordering-agent, and use that name in your sentences. Names are unique within your organization. The signed grant still names the key, and the read-back shows both.

There are three ways an agent gets onto your list:

• Add it yourself. Choose Add an agent, paste the agent ID from whoever runs it, and name it. It's ready for authority straight away.
• Let your builders' systems add their agents. Create an enrolment token. It can do one thing: add an agent to your list. It expires (30 days by default, 90 at most) and you can revoke it. An agent added this way waits for your approval.
• Connect a vendor's agent. Choose Connect a vendor's agent and create a one-time code, which lasts 24 hours. The vendor's agent uses it to join your list, and it waits for your approval too. The vendor never gets any power to give its agent authority; only your company signs its grants.

Anything waiting shows as Waiting for your approval. Approve it, rename it first if you like, or Turn away. Only approved agents can be named in a sentence.

Give authority#

1. Write what the agent may do in your own words, in Let this agent…. Delegus turns the sentence into a draft grant. You approve the grant, never the sentence.
2. Read the grant back. Every line says only what the check will read: the agent, what it may do, the limits, the dates. Show the exact grant and its fingerprint shows the raw values under each line.
3. Approve with your passkey. You have ten minutes, and a draft can be approved once.
4. Delegus signs exactly those bytes and gives you the signed grant to hand to your agent, the same as a grant you signed yourself.

What you can write#

The console reads a short sentence and turns it into the exact grant. It never guesses: anything it doesn't understand is refused, quoting the words it couldn't read.

• Any supplier with a name that starts the same way: "Let ordering-agent pay any supplier starting with acme- up to $250 each purchase until 2026-12-31." Write the dash: "starting with acme" would also match acmetools.
• Several suppliers: "Let ordering-agent pay castings-co or northfield-supply up to $2,000 a day until 2026-12-31." A daily or weekly limit is one budget shared across all the names, not one each.
• An ordinary web API: "Let support-agent read and create at https://api.example.com/tickets and everything under it until 2026-12-31." Give the full address; the path is never guessed. "And everything under it" covers the address and everything below it.
• How often a limit resets: "each purchase", "a day" or "a week".

The approval record#

Each approval leaves a record: which grant, which person, which passkey, and the passkey's full signature over the grant's exact bytes. It's shown to your company once, when you approve, and Delegus keeps it as private evidence for seven years, where nobody, Delegus included, can change or delete it.

Because the full signature is kept, anyone holding the record can re-check that this person approved these exact bytes without asking Delegus. The tools for that (delegus approval verify) come with the next SDK release.

Next to your own key#

The grant Delegus signs is an ordinary grant under a key in your DID document. Businesses that check your agent see nothing different, and receipts don't change.

To move to your own key later, add it to your identity, then switch custody to yourself. Delegus's key stops signing but stays published, so the grants it already signed keep verifying.

To sign with your own key from the start, use the CLI instead:

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.

grant explain reads any grant back in plain words. Both are in @delegus/sdk 0.3.2 and later. The newer sentence forms above ("starting with", names joined by "or", "and everything under it") work in the console today; on the command line they come with the next SDK release.

Limits#

• Hosted identities only, as above.
• One approver per grant today. There's no two-person rule for large amounts yet.
• Revoking a grant still uses an API key, as before. It doesn't ask for a passkey.