Developers · SDK and public read API
Two ways in.
Pick the one that is yours.
You arrive with one of two tasks: verify agents that reach your API, or register an agent of your own. The code on this page is checked against the ARIA SDK 1.0.0 and ARIA AP 1.0.0 packages.
Pick your door
I verify agents that reach my API
Check the credential an agent presents with the ARIA SDK: the AID 1.0 schema, an issuer you trust, both halves of the composite signature, the validity window and the holder key, then the status of that exact document from the issuer's signed list. That tells you the credential is genuine and current. It does not tell you that the caller holds its key, or what it may do: admitting a request is ARIA AP's job.
npm install @trustlayer-foundation/aria-sdkimport { createVerifier } from '@trustlayer-foundation/aria-sdk';
// issuer: an issuer you trust, with its two public keys and the status
// lists it publishes. The SDK trusts no issuer by default: you state the
// keys you trust. Today's issuer, did:aria:registry.aria.bar, is a
// demonstration: take its keys from its key set only under the anchor
// fingerprint you pinned.
// credential: the AID the agent presented, or /v1/aids/<did> on api.aria.bar.
const verifier = createVerifier({
trust: [issuer],
fetch: { allowedOrigins: ['https://api.aria.bar'] },
});
const checked = verifier.verifyCredential(credential);
if (!checked.ok) throw new Error(`credential refused: ${checked.reason}`);
// The status of this exact document, from the issuer's signed list, then
// whether it stands now: good, revoked, superseded, not_valid_now or
// unknown. Unknown is never good.
const status = await verifier.checkStatus(checked.credential);
const standing = verifier.standing(checked.credential, status);
console.log(checked.credential.did, checked.credential.trustLevel, standing.state);
// Genuine and current is not permission to act: deciding what an agent
// may do is ARIA AP's admission.Trust is yours to state. The SDK trusts no issuer by default: you give it each issuer you accept, with its two public keys, the highest level you accept from it and the status lists it publishes. The issuer that runs today, did:aria:registry.aria.bar behind agent.bar, is a demonstration: its credentials are not a production guarantee. Its key set is served at https://api.aria.bar/v1/keyset. Take its keys from there only after checking its anchor fingerprint, sha256:4117aaac21272740756d02305a9fa7e2d84398fdd859d390b476539d57ec67b3, which you pin yourself, under a trust profile you name demo.
What each result establishes
| Call | Establishes | Does not establish |
|---|---|---|
| verifyCredential | The AID 1.0 schema, an issuer you trust, the proof profile, both signature halves, the validity window, the holder key, and a level and status list your profile accepts | Who presents it; its status |
| checkStatus | The status of that exact document, active or revoked, from the signed list it names; or unavailable, with a reason | Anything about another document of the same DID |
| standing | Whether it stands now: good, revoked, superseded, not_valid_now or unknown. Unknown is never good | That anyone presents it, or may act |
| ARIA AP admit | allow, deny or indeterminate for one signed request, after the caller proved its holder key | That the operation ran: the operation ledger and its receipt say that |
Admit a request with ARIA AP
ARIA AP authenticates the request, then decides. The agent signs each request with its holder key under RFC 9421, for your receiver, with a single-use challenge you issued. You verify the credential and its status, then audience, level, scope, delegation and human approval, then your own rule. Only allow runs, once per operation. Each operation's outcome is a signed receipt, and so is each attempt refused at admission. Two answers are not: a request that fails authentication gets an unsigned 400 or 401, and a retrieval returns the stored receipts with none of its own, its refusals unsigned.
npm install @trustlayer-foundation/aria-sdk @trustlayer-foundation/aria-apimport { createVerifier } from '@trustlayer-foundation/aria-sdk';
import { createAp, OperationLedger, type HttpRequestLike, type OperationDescriptor, type ReceiverSelf } from '@trustlayer-foundation/aria-ap';
// One verifier, with the issuers you trust. ARIA AP reads every credential through it,
// your own included: a credential another verifier produced is refused.
const verifier = createVerifier({ trust: [issuer], fetch: { allowedOrigins: ['https://api.aria.bar'] } });
const ap = createAp({ credentials: verifier });
// Your own identity: your AID, verified by that same verifier, and its holder key.
const own = verifier.verifyCredential(ownDocument);
if (!own.ok) throw new Error(`our own credential: ${own.reason}`);
const self: ReceiverSelf = { did: own.credential.did, origin: 'https://bank.example', credential: own.credential, document: ownDocument, signer: holderKey };
const ledger = new OperationLedger(ap, storage, self); // storage: your database
const transfer: OperationDescriptor = {
name: 'transfer', class: 'unsafe-body', method: 'POST', path: '/v1/transfers',
mediaType: 'application/json', scope: 'payments:transfer:create', minLevel: 'L1',
onMissingApproval: 'refuse', // a hitlRequired scope without a valid approval is refused
};
/** GET /.well-known/aria/identity?nonce=…&audience=…: who you are, and a challenge for the next request. */
export function identity(nonce: string, audience: string) {
return ap.identify(self, { nonce, audience }, challenges);
}
export async function handle(request: HttpRequestLike) {
// 1. The request is signed with the agent's holder key (RFC 9421), for this
// receiver, operation and content, with a challenge you issued. Unsigned answer.
const presented = await ap.verifyPresentation(request, {
receiver: { did: self.did, origin: self.origin }, operations: [transfer], challenges, resolveCredential,
});
if (!presented.ok) return { status: presented.status };
// 2. Admission: the credential and its current status, audience, level, scope,
// delegation and human approval, then your own rule. Only allow runs.
const status = await verifier.checkStatus(presented.presentation.credential);
const admission = await ap.admit({ presentation: presented.presentation, status, authorize });
if (admission.decision !== 'allow') {
// A signed refusal of this attempt only.
return { status: admission.refusal.status, receipt: await ap.buildAttemptRefusal(admission.refusal, self) };
}
// 3. Once per operation: a retry gets the original receipt, never a second transfer.
const begun = await ledger.begin(admission);
if (begun.kind === 'existing') return { status: begun.status, receipt: begun.governing };
if (begun.kind === 'refused') return { status: begun.refusal.status, receipt: await ap.buildAttemptRefusal(begun.refusal, self) };
// 4. The transfer and its recorded outcome commit in one transaction; the receipt
// comes from that record.
try {
const outcome = await inTransaction(async () => {
await moveMoney(request.body);
return ledger.settle(begun.claim, { state: 'completed', status: 201 });
});
return { status: outcome.status, receipt: outcome.receipt };
} catch (error) {
// No receipt either way. Release the operation only when you know the transaction
// rolled back. Otherwise it stays locked, and retries get 409 aria.operation_in_progress,
// until ledger.reconcile is given an assurance that this worker can no longer commit
// it. Never run the transfer again to find out.
await ledger.fail(begun.claim, rolledBack(error) ? 'rolled-back' : 'uncertain');
return { status: 500 };
}
}Already on @aria-registry/verify 1.1.0?
It is no longer served by npm, though a copy you already installed still runs. It verifies preview-line credentials offline; its embedded keys do not verify the current authority's credentials. It does not check revocation, and its valid is not a decision to act: it can be true with the status unchecked and nobody proving the holder key. Moving to 1.0 means one verifier for credentials and ARIA AP for admission.
Migration guide ↗I register my agent
Registration happens at agent.bar, the registry operated by Tunolabs. The Create flow is the one specified in §3.5.1, and the agent's private key never leaves the machine it runs on.
- 01Sign in at agent.bar and open an enrollment window: its seats, its allowed scopes and a short validity, confirmed with a code sent to your email.
- 02Hand the window's ARIA.md to the agent. It is the invitation: whoever holds it can enroll while seats remain.
- 03The agent generates its keys where it runs and enrolls with the enrollment client, declaring its name and its scopes in the three-segment grammar; only the public keys leave its machine.
- 04Receive the AID: a W3C Verifiable Credential signed with the composite suite, resolvable at api.aria.bar/v1/aids/<did>.
L0 needs only the agent's keys. L1 adds a verified person and the account's domain, bound once with an _aria-bind TXT record. L2 adds the organization, and L3 a Binding Officer with the power to bind it. →
Public read API — the authority's gateway
Public read API.
Base URL https://api.aria.bar. Every endpoint below is read-only and public; there is no write endpoint on this host. The table is generated from the gateway's router, not written by hand: a route the gateway does not serve cannot appear here.
/health● liveLiveness.
The current AID (W3C VC) for a did:aria. It returns the credential, not a DID Resolution result; the DID Document is derived client-side (§3.2).
One credential instance by its id, including superseded and revoked ones.
The W3C Bitstring Status List credential (u-prefixed base64url GZIP), valid 24 hours and re-signed hourly.
Server-side check of the DID's current credential: both signatures, validity, revocation, level. It is a lookup by DID, so the API learns which identifier you check; the status list does not tell it.
Generated from the gateway router on 2026-10-31 · scripts/gen-api-routes.mjs
The demonstration issuer's key set is served at https://api.aria.bar/v1/keyset: every key it has signed with, the first one the anchor. Take its keys from there only after checking the anchor's fingerprint, which you pin yourself under a trust profile you name demo.
Pin the anchor and verify offline →Revocation is published as a W3C Bitstring Status List, addressed by list id: GET /v1/status/1 is the list every credential issued so far points at. Your credential names its own position in credentialStatus.statusListIndex; that bit is the answer. Verify the list’s composite proof before reading it — both halves, as for an AID — because an unverified list is a claim over transport security, not evidence. The list is also the private way to ask: GET /v1/verify/{did} answers for a DID's current credential, but that lookup tells the API which identifier you check. Anything that is not a list id answers 404.
Step by step, with the ARIA SDK →SDKs and conformance
Two packages for 1.0. Both on npm.
| Install | When you want to |
|---|---|
| ARIA SDK | Show or record whether an agent's credential is genuine, current and not revoked |
| ARIA SDK and ARIA AP | Decide whether an agent's request may run, or call such a service as an agent |
# credentials and their status
npm install @trustlayer-foundation/aria-sdk
# requests, admission and receipts
npm install @trustlayer-foundation/aria-sdk @trustlayer-foundation/aria-apThe two 1.0 packages are on npm: @trustlayer-foundation/aria-sdk ↗ · @trustlayer-foundation/aria-ap ↗
TypeScript · ARIA SDK 1.0 · @trustlayer-foundation/aria-sdk
Credential verification and the status of the exact document: the AID 1.0 schema, an issuer you trust, the proof profile, both halves of the composite signature judged once (ML-DSA-65 and Ed25519; one half alone never passes), the validity window and the holder key; then the issuer's signed status list, and a standing that is good only with fresh evidence. None of it is permission to act.
TypeScript · ARIA AP 1.0 · @trustlayer-foundation/aria-ap
Receiver identity, requests signed under RFC 9421, admission, one execution per operation and signed receipts, built on the ARIA SDK's verifier. One receipt format, aria-ap-receipt/1; three-segment scopes; a lost answer recovered by a signed lookup of the original receipts.
@aria-registry/verify 1.1.0 · no longer on npm
The earlier package, no longer served by npm. It verified preview-line credentials offline; it did not check revocation, and its valid was not a decision to act. The two packages above replace it.
Questions and bugs: GitHub issues ↗. Security vulnerabilities: security@trustlayer.foundation, never a public issue.
Published in trustlayer-foundation/aria-protocol: the cases every implementation checks itself against. The schemas govern a credential's shape and the specification its meaning; where an implementation, a vector or the text disagree, that is a bug to report.
Claude and other MCP clients
Expose the verifier's verifyCredential and checkStatus as a tool in your MCP server, or call the public read API over HTTP from one.
LangChain / LangGraph
Wrap the verifier's verifyCredential and checkStatus in a tool function, or call the read API over HTTP. There is no ARIA-specific package for these frameworks.
AutoGen / CrewAI
Same pattern: the verifier as a tool in the agent's toolbelt, its result treated as identity information. An agent that calls ARIA AP receivers signs its requests with its holder key, kept outside the model.
SPIFFE / SPIRE
Complementary. A SPIFFE SVID identifies a workload inside one trust domain; an AID identifies an agent across organizations. Bridging pattern: spec Appendix D.
What runs
What runs, and where.
- api.aria.bar public read API
- agent.bar, L0 issuance
- The demonstration issuer's key set at api.aria.bar/v1/keyset →
- ARIA SDK 1.0 and ARIA AP 1.0 on npm →
Start where it runs: verify, then admit with ARIA AP.
Verify credentials with the ARIA SDK and read their status from the issuer's signed list; admit requests with ARIA AP. Registration of your own agents is at agent.bar; the registry is the party that verifies and issues.