Publish an adapter
You need an owner or admin account in your organisation on Adapter Studio,
and either the zaitrack command (the quick path below) or openssl and jq (the manual path, steps 1 to 5).
The zaitrack adapter command and Adapter Studio use the same files and the same registry: adapter.json (the
manifest), manifest.canonical.json (the bytes that are signed) and signature.b64 (ECDSA P-256 over their SHA-256).
Make them with the command and send them with zaitrack adapter submit or paste them into the studio; or make them
by hand as below. The older --legacy-ed25519 signature (signature.json) is for adapters ZAITRACK builds inside its
own monorepo and is not accepted.
Quick path: the zaitrack command
zaitrack adapter scaffold connector --name acme-fleet-export --display-name "Acme fleet export" \
--licence MIT --publisher acme --out ./work # ./work/acme-fleet-export/manifest.yaml and the skeleton
zaitrack adapter test ./work/acme-fleet-export # conformance pack: golden vectors, fuzz, scenarios
zaitrack adapter pack ./work/acme-fleet-export # adapter.json and manifest.canonical.json
zaitrack adapter keygen --out ./keys # key.pem (private, 0600), key.pub.pem, the fingerprint
zaitrack adapter sign ./work/acme-fleet-export --key ./keys/key.pem # signature.b64
zaitrack adapter verify ./work/acme-fleet-export --public-key ./keys/key.pub.pem
zaitrack adapter submit ./work/acme-fleet-export --registry https://<registry> \
--token ZAITRACK_REGISTRY_TOKEN --key ./keys/key.pem --create-project
- The directory name is the project's slug and the manifest's
id(3 to 64 characters, lowercase letters, digits and hyphens). The licence, summary and description belong to the project, not the manifest: they come frommanifest.yamlwhen--create-projectcreates it (--visibility public|tenant-only, defaulttenant-only). packrefuses what the registry would refuse, with the field named: slug, version, display name, availability, family, config keys and types, notices, a codec's device classes. A codec's built module goes in with--module, which pins its SHA-256 in the manifest.ZAITRACK_REGISTRY_TOKENis the name of the environment variable holding an owner's or admin's Bearer token; the token is never a flag and is never printed.--registryis the registry's address behind the gateway, as your ZAITRACK contact gives it; the command calls its/adapters/v1routes over https.submitregisterskey.pub.pemfirst when the registry does not know its fingerprint, then submits the version with the artifact's address, SHA-256 and size when you give--artifact-url,--artifact-sha256,--artifact-size(or--module). The version waits aspending-review; steps 6 and 7 follow.- The studio alternative: Signing keys → Register a key with
key.pub.pem, then Projects → your project → Submit a version with the content ofadapter.jsonandsignature.b64. A codec's module is uploaded there too.
1. Make a signing key
ZAITRACK accepts one algorithm: ECDSA on the P-256 curve over SHA-256, the signature in ASN.1 DER, base64.
openssl ecparam -name prime256v1 -genkey -noout -out key.pem
openssl ec -in key.pem -pubout -out key.pub.pem
Keep key.pem secret: anyone holding it can sign versions as you. In Adapter Studio, Signing keys → Register a
key, give it a name (2 to 80 characters) and paste key.pub.pem. The studio shows the key's fingerprint,
SHA256: and the base64 SHA-256 of the DER public key.
2. Create the project
Projects → New project: a slug (lowercase letters, digits and hyphens), the family (codec,
connector, datasource, action or ai), a display name, a summary and description, an SPDX licence
(LicenseRef-… for your own) and the visibility: public (any organisation can see and install its approved
versions) or tenant-only (your organisation only).
3. Write the manifest
adapter.json says who the adapter is, what it can do, the permissions it asks for and the settings an
installation must give:
{
"id": "acme-fleet-export",
"family": "connector",
"version": "1.0.0",
"displayName": "Acme fleet export",
"capabilities": ["export"],
"permissions": ["trips:read"],
"config": [
{"key": "sftpHost", "type": "url", "required": true, "label": "SFTP host"},
{"key": "password", "type": "secret", "required": true, "label": "Password"}
]
}
id: 3 to 64 characters, lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen. The version must be new for the project.version: semantic versioning (1.0.0,1.1.0-rc.1).displayName: at least 3 characters.config[].key: a letter, then letters, digits or_(48 at most), each key once.config[].type:text,number,url,secretorport. Asecretsetting is never shown back once given.
4. Sign the canonical manifest
The registry signs and checks the canonical manifest: keys sorted, no insignificant whitespace, no trailing
newline. Make it with jq, then sign it:
jq -cSj . adapter.json > manifest.canonical.json
openssl dgst -sha256 -sign key.pem manifest.canonical.json | base64 -w0 > signature.b64
Keep the characters &, < and > out of the manifest's strings: the registry writes them as \u0026,
\u003c and \u003e and jq does not, so the signature would not match. On macOS, use base64 without -w0
(it does not wrap).
5. Submit the version
Projects → your project → Submit a version: paste adapter.json, the content of signature.b64 and choose
the key. Optionally give the artifact's address (https:// or oci://). The registry makes the manifest canonical,
hashes it with SHA-256 and checks the signature against your key. A wrong signature or a revoked key is refused.
The version waits as pending-review.
6. Review
ZAITRACK staff run the conformance suite and record its result: coverage and how many checks passed and failed. A version is approved only with a run of at least 85 % coverage and no failures; staff approve with a note, or reject with a reason.
7. Installations
Organisations install an approved version and fill in the settings your manifest declares. They can upgrade to another approved version, change settings, suspend, resume and uninstall. You see one installation per organisation, with its version and status.
An active installation is a registry state, not proof of a connected device or a prepared runtime. Before deployment, follow Codec readiness; keep approval, installation and device evidence separate.
Revoking a key
Signing keys → Revoke, with a reason. In one step it revokes every version that key signed and suspends their installations; the key goes on the revocation list with when and why. An installation resumes once it is upgraded to a version that is not revoked: sign the next version with a new key.