Mandate

A person twin acts for a human. The mandate proves it. The human signs a TwinMandateCredential for their twin with the device key of the AY app. Anyone can verify it without trusting AY.

• The issuer is the human (the user DID), not the platform.
• The subject is the twin DID.
• The mandate sets an upper bound: an approval level and the capabilities the twin may use without asking.
• A business twin has no mandate of a person. For a business twin, the Business Verification Credential counts.

FormatCopy Anchor Link

The mandate uses the same format as the other AY credentials: vc+jwt with claims in SD-JWT VC style.

The signature is ES256 as defined in RFC 7518, section 3.4: ECDSA P-256 over SHA-256 of header.payload, encoded as raw R‖S, 64 bytes. A DER-encoded signature is invalid. High-S signatures are accepted.

A new mandate replaces the previous one. The human signs again to raise the approval level or to renew the mandate.

Verification pathCopy Anchor Link

A signed call from an agent leads to a human in three steps: agent → twin → human.

1. Agent → twin. The agent passport names the twin in owner, and the agent DID document names it in controller.
2. Twin → human. The twin DID document names the user DID in controller. The mandate at the twin DID proves this binding with the human's signature.
3. The mandate itself. Check it with these rules:
   • iss equals the controller of the twin DID document (sub). Otherwise the mandate is invalid with reason issuer_not_controller.
   • kid is <iss>#key-device, and the user DID document lists that key under assertionMethod.
   • alg is ES256, and the signature is 64 bytes raw.
   • exp is in the future, and the status list bit is 0.

There is no issuer allowlist for mandates. AY never issues a mandate; only the human does.

GET /api/v1/identity/resolve of a person twin returns the current mandate in credentials. POST /api/v1/identity/credentials/verify applies the rules above and returns one verdict.

curl -X POST https://api.aytwin.ai/api/v1/identity/credentials/verify \
  -H "Content-Type: application/json" \
  -d '{"jwt": "eyJ…"}'

Status listCopy Anchor Link

Mandates have their own list at GET /api/v1/identity/status-list/mandates. It uses the same format and values as the other status lists. Every mandate gets a new index; an index is never reused.

The verifier reports expired from exp on. AY keeps the bit at 0 for a grace period of 30 days after exp, so that the human can renew. Rely on the verdict, not on the bit alone.

Mandate and Sign & CommitCopy Anchor Link

The mandate never replaces Sign & Commit. A binding commitment, such as a purchase or a contract, always needs the human's approval for that single action, even with a valid mandate. The mandate covers what the twin may do on its own; Sign & Commit covers what binds the human.

When a mandate is missing or revoked, the twin asks the human before it acts instead of acting on its own.

EnforcementCopy Anchor Link

AY enforces the mandate for person accounts only when enforcement is on in the environment. Then:

• POST /agents, POST /agents/{id}/attest and key rotation return 409 MANDATE_REQUIRED without a valid mandate.
• Every authenticated request of an agent that belongs to a person returns 403 OWNER_MANDATE_MISSING without a valid mandate, from the moment the human revokes it.

See Errors. A test vector is in Test vectors.