Quickstart

First receipt, checked offline.

These commands were run exactly as written on a clean machine (empty home directory, only the two executables). Expected output is shown under each step.

You need

Executablesardyn-connect 0.1.0 and ardyn-verify 0.1.0+wx004 (macOS arm64 or Linux x86-64; on request from enterprise@ardyn.ai)

An HTTP APIAny service with an OpenAPI 3.0 or 3.1 description. The example uses a disposable test service on 127.0.0.1:8802.

Toolscurl and python3 (only to send JSON in this example)

Already using an assistant?

To connect an MCP client to Ardyn instead, see ACTA MCP. To check a public ledger entry, use Verify.

Steps

1 · Create a workspace key
```
ardyn-connect tenant --data ./data "my-workspace" > tenant.json
```
Writes {"tenant_id": …, "api_key": "ak_…"}. The key is shown once. The runtime stores only its hash.
2 · Start the runtime
```
ARDYN_CONNECT_ALLOW_PRIVATE=1 ardyn-connect serve --data ./data --listen 127.0.0.1:8790
curl -s http://127.0.0.1:8790/v1/health
```
```
{"service":"ardyn-connect","status":"ok","version":"0.1.0"}
```
ARDYN_CONNECT_ALLOW_PRIVATE=1 is only for reaching services on your own network or machine, as in this example. Without it, connections may only reach public HTTPS hosts, and private and metadata addresses are refused.

3 · Connect the API from its description

curl -s http://127.0.0.1:8802/openapi.json > api.json
POST /v1/connections
{"family": "http_openapi", "name": "Asset Ledger",
 "config": {"base_url": "http://127.0.0.1:8802", "openapi": "<contents of api.json>",
            "destination": {"allow_private": true}}}

connection 5f1c… active

Importing calls nothing. Unsupported operations are listed with the reason (here, a multipart upload).

4 · Enable a read and run it

GET  /v1/capabilities?connection=<connection id>
POST /v1/capabilities/<url-encoded capability id>/enable  {"effect_class": "read"}
POST /v1/capabilities/<url-encoded capability id>/invoke  {"arguments": {"path": {"asset_id": "a-100"}}}

operation committed receipt ecf2f506-…

All calls use Authorization: Bearer <api_key>. Capability ids contain / and @, so percent-encode them as one path segment.

5 · Export the receipt and verify it offline

GET /v1/receipts/<receipt id>/export   → receipt.json
ardyn-connect trust --data ./data > trust.json
ardyn-verify receipt.json --trust trust.json --expect-tenant <tenant id>

result       Supported
  [         PASS] profile.supported — bundle profile ardyn-bundle/2
  [         PASS] inventory.binding — all 8 covered sections re-derive to the signed manifest inventory
  [         PASS] commitments.rederive — 2/2 artifact commitments re-derived from embedded raw bytes
  [         PASS] signature.math — Ed25519 over the canonical manifest bytes
  [         PASS] signer.trust — trust config ardyn-connect/7a7832a663bbdcec (1 key(s))
  [         PASS] tenant.binding — 0 artifact(s) belong to a different tenant than the manifest
semantic     blake3:708cb85a…

Exit code 0 means SUPPORTED. Any other result exits 1. The semantic digest is the same one /verify shows for the same files.

If something fails

destination_refusedThe URL is not on the connection’s allowlist or resolves to a private address. Use a public HTTPS host, or run the runtime on that network with ARDYN_CONNECT_ALLOW_PRIVATE=1.

unsupported_specThe description is Swagger 2.0, too large, or not valid JSON/YAML. The message says which.

capability_not_enabledDiscovery grants no authority. Enable the operation first.

Result Unverifiable with SIGNER_UNTRUSTEDThe trust file is not the one for the runtime that signed the receipt.