Use cases

DID.is answers one kind of question: “What can actually be shown about this identifier, credential or agent, and what cannot?” The six situations below show where that question comes up. Each one lists what DID.is checks, what the answer proves, what it leaves for you to decide, and the request to make.

A plain-language picture

A DID is like a digital business card that its owner publishes and controls. The card lists the owner’s public keys and, for did:web, lives on the owner’s own website. Anyone can read it; nobody needs a central registry to issue it.

DID.is is the inspector who reads the card and writes down what was checked: whether the card is intact, whether the keys on it are usable, whether the website links back to it, and whether its past versions can be proven. It does not say “trust this card”. It says “here is what the evidence shows, and here is where the evidence stops”. The decision stays with you.

PartnershipsCheck a business partnerIs this identifier really run from the partner’s domain?Hiring and onboardingVerify a digital certificateIs this credential signed by its issuer and still active?AI agentsLet an agent act only with permissionWas this agent delegated the right to use this tool?AI toolingReview an MCP serverWhich tools does it expose, and did they change?OperationsGet told when an identifier changesA signed webhook when a document, key or binding changes.Platform teamsVerify signatures at the gatewayWas this request signed by a key of the sender’s DID?

Check a business partner

Situation. A supplier sends you its identifier, did:web:supplier.example, and asks you to accept invoices signed with it. Before you add it to your systems, you want to know that the identifier is published from the supplier’s own domain and that its keys are usable.

Supplierdid:web:supplier.example

DID.is checks

Document fetched over trusted TLS
Website links back to the DID
Keys well-formed and usable
Your rules: method, binding, certificate

Your onboarding teamPASS · 4 of 4 rules

What the answer shows

The document is served from that domain over a publicly trusted certificate.
The domain publishes a DID Configuration that links back (origin binding).
Each of your rules passed or failed, with a reason.

What it does not show

That the domain belongs to the company you think it does. Legal identity is never verified.
That the supplier is reliable to do business with.

Write your acceptance rules once and evaluate every partner against them:

curl -X POST https://did.is/api/v1/policies/evaluate \
  -H 'content-type: application/json' \
  -d '{"did":"did:web:did.is","policy":{"name":"partner-onboarding","rules":{"didResolution":"required","allowedMethods":["web","webvh"],"domainBinding":"required","tlsMinDaysRemaining":14}}}'

For did:web:did.is this returns PASS with “All 4 evaluated rules pass.” See Policies for every rule.

Verify a digital certificate

Situation. A candidate sends a digital diploma as a W3C verifiable credential. You want to know whether the university’s key really signed it, whether it is within its validity dates, and whether the university has revoked it.

Candidatepresents a credential

DID.is checks

Issuer's DID resolves
Signature matches the issuer's key
Validity dates include today
Revocation status list is clear

RecruiterVALID

What the answer shows

The credential was signed by a key the issuer’s DID authorises.
It has not expired and, if it has a status list, is not revoked or suspended.
Which check failed, if any, in plain words.

What it does not show

That the issuer is a real university, or allowed to award that degree. Decide which issuers you accept.
That the candidate is the person named in it.

curl -X POST https://did.is/api/v1/credentials/verify \
  -H 'content-type: application/json' \
  -d '{"credential": { … }}'

Accept only VALID. INDETERMINATE means a check could not finish, for example an unreachable status list, and is not a pass. See Credentials.

Let an AI agent act only with permission

Situation. A bank lets a customer-service AI agent issue refunds. The bank delegated that right to a vendor, and the vendor delegated it to the agent. Before the refund tool runs, your gateway needs to confirm the chain of permission really leads back to the bank.

AI agentwants payments.refund

DID.is checks

Every receipt is signed by the delegator
Chain starts at a root you trust
No link widens the permissions
Leaf allows this tool and has not expired

Tool gatewayALLOW or DENY

What the answer shows

Who delegated what to whom, link by link, back to did:web:bank.example.
Whether the agent’s final permissions include payments.refund, with a reason when they do not.

What it does not show

That the agent will behave within its permissions.
That the refund itself is correct. Delegation receipts are an experimental DID.is format, not a ratified standard.

curl -X POST https://did.is/api/v1/agents/authorize \
  -H 'content-type: application/json' \
  -d '{"chain":["<root receipt>","<leaf receipt>"],"tool":"payments.refund","trustedRoots":["did:web:bank.example"]}'

An empty or broken chain is always denied: {"decision":"DENY","reason":"A chain must contain between 1 and 8 receipts."}. See Authorise a tool call.

Review an MCP server before connecting

Situation. Your team wants to connect an assistant to a third-party MCP server. You want to see which tools it exposes before approving it, and you want to notice if those tools change after you approved them.

MCP servermcp.deepwiki.com

DID.is checks

Every tool listed
Each definition fingerprinted
Read-only or side effects, estimated
Compared with the last observation

Security reviewerdrift: UNCHANGED

What the answer shows

The tools the server exposes today and a SHA-256 fingerprint of each definition.
Whether a tool changed since it was last seen (FIRST_OBSERVATION, UNCHANGED or CHANGED).

What it does not show

That the server is safe. Its self-description is inspected, not certified.
Tools behind a login. A server that needs OAuth returns AUTH_REQUIRED.

curl 'https://did.is/api/v1/mcp/inspect?endpoint=https://mcp.deepwiki.com/mcp'

Store the fingerprints of the tools you approve. If one changes, review it again. See Inspect an MCP server.

Get told when an identifier changes

Situation. Your product accepts signatures from a few dozen partner DIDs. If one of them rotates its keys, loses its domain binding or stops resolving, you want to know within the hour rather than when a customer complains.

Watched DIDschosen in the console

DID.is checks

Document hash compared
Domain binding compared
Resolution failures and recoveries
Signed event on any change

Your webhookdocument.changed

What the answer shows

That the document changed, with the old and new hash and a diff.
That the domain binding changed, or the identifier stopped or resumed resolving.

What it does not show

Why it changed or who changed it. A key rotation can be routine.
Changes between two hourly checks that were reverted.

Monitoring is a console feature: create a project, add identifiers and a webhook URL, then verify each delivery’s signature. See Monitoring and webhooks.

Verify signatures at the gateway

Situation. Partners call your API with requests signed as compact JWS, with their DID in the kid header. Your gateway needs a fast yes or no on every request.

Partner appsigned request

DID.is checks

Sender's DID resolved
Key is in the DID document
Key is allowed to sign
Signature verifies

Your API gatewayvalid: true

What the answer shows

The JWS was signed by a key the sender’s DID lists under assertionMethod or authentication, or the relationship you name.
The decoded payload and the signer.

What it does not show

That the request is not a replay. Check timestamps or nonces yourself.
That the sender is allowed to call that endpoint. That is your access policy.

curl -X POST https://did.is/api/v1/fast-verify/jws \
  -H 'content-type: application/json' \
  -d '{"jws":"eyJhbG…"}'

Uses the standard budget (20 requests per minute). For a compact verdict on a DID alone, use GET /v1/fast-verify/did/{did}. See Verify a JWS against a DID.

Next steps

Quickstart: your first request in under five minutes.
Core concepts: the seven evidence dimensions and their states.
API reference: every endpoint with curl, TypeScript, Python and Rust samples.