API keys

API keys is where an owner enrols your people’s machines and manages the keys they hold. Owners open it under Connections in the sidebar, or from Menu on smaller screens. A member reaches one card there, Enrol this machine, for their own machine, from the entry of that name under Connections, at <the hub's address>/settings/api-keys#enrol, replacing <the hub's address> with their Common Measure Hub address. Fleet evidence shows the same card while nothing has been received.

Each enrolled machine holds two keys, both under the name given at enrolment:

• an ingest key, which lets the machine deliver to your organisation and read only the hub’s policy signer (policy distribution), which the machine pins;
• an edge key, which the machine signs its fetches with, so a publisher can check that a request came from one of your enrolled machines.

To stop a machine delivering, revoke its ingest key. To stop publishers accepting its signature, revoke its edge key. To remove a machine altogether, revoke both. A machine whose keys were revoked is enrolled again, with a new code or a new enrolment token.

Enrolling a machine

The enrol card prints the install command with no token first; Copy install command copies it. On a machine without Common Measure, the person who works on it runs it in the project directory whose sessions the hub should see:

curl -fsSL https://github.com/commonmeasure/commonmeasure/releases/latest/download/install.sh | sh -s -- --connect <the hub's address>

It installs the commonmeasure binary, registers it with every agent host it finds on the machine and connects the machine to the hub: it prints a short code, which the person approves at <the hub's address>/connect, signed in (Connect an edge). It then enrols the directory for reporting and relays its first evidence. It asks the reporting-consent question itself, and prints the command that confirms the directory’s earlier history rather than confirming it. Run from the home directory or /, it enrols no directory. Between approval and the machine’s next poll, a few seconds, the approval is listed under Enrolment tokens awaiting exchange, where an owner can cancel it.

With an enrolment token

To enrol a chosen member’s machine without being at it, an owner mints a token instead. Mint enrolment token prints two commands with the token in them; Copy token install command and Copy connect command copy each. The token works once, so run one of them.

On a machine without Common Measure, run the first in the project directory; it does what the command without a token does, with no code to approve:

curl -fsSL https://github.com/commonmeasure/commonmeasure/releases/latest/download/install.sh | sh -s -- --connect <the hub's address> --token et_…

On a machine that already has the binary, run the second:

commonmeasure connect <the hub's address> --token et_… --managed

Every route enrols the machine with the same two keys, listed here like any other, pins the hub’s policy signer and makes a first sync of the policy published on Policy (Connect an edge). Fleet evidence shows the card too while nothing has been received, and shows the first session when it arrives (Fleet evidence).

Whose machine it is

Every machine belongs to the member it was enrolled for. Under Enrol an edge, choose the member from Member, which starts with no one chosen; the token alert names the member it was minted for. A member’s Enrol this machine mints for themselves. On Connect an edge, a member approves a code for their own machine and an owner for any member.

Edge keys and Enrolment tokens awaiting exchange show the member beside each machine. A machine enrolled before machines had members shows “No member” and belongs to no one; Policy and Fleet evidence show it the same way.

Remove on Team revokes both keys of every machine enrolled for that member, cancels their unused enrolment tokens and signs them out. The member’s name is shown to owners on this page and in Fleet evidence, and is never in a report handed to a content owner.

Release and key directory

Edge keys shows the Common Measure release each machine reported the last time it renewed its listing signature, or “Not reported” when it reported none. Key directory shows whether the key directory lists the machine’s key now, which publishers need to verify its requests. “Not listed” gives the reason, such as a release below the hub’s minimum (0.4.1) or no listing signature yet. A machine running a supported release is listed once it renews its signature (Bot identity).

Revoking

Revoke asks once more with Confirm revoke. The revocation takes effect on the next request. The keys list shows when a key was revoked; Edge keys also shows who revoked it, or that the machine disconnected itself. API-key revocation records the person making the change in the audit log. A revoked key cannot be revealed or used again.

An edge key leaves the public list publishers check at once; a publisher that saved the list keeps accepting the key for up to an hour. Anything a machine had not yet delivered stays on the machine.

Other keys

The Mint a key form offers one option per job, each naming what the key may do:

• Telemetry ingest (telemetry:ingest): for a machine that cannot run commonmeasure connect (Connect an edge). Delivers, and reads only the policy signer.
• Telemetry read (telemetry:read): for a reporting tool that reads the fleet evidence without a signed-in person.
• Identity (identity:read, identity:write): for managing members over the API.

A key can be revealed again from the page at any time; every reveal is recorded with who did it, which key and when, and listed under Reveals. There is no key for fetching policy: an enrolled machine signs that request with its edge key (policy distribution).

A key used for something it may not do is refused with both what it lacks and what it carries:

{ "detail": "credential lacks the telemetry:ingest scope; it carries identity:read, identity:write" }

For operators

Keys are sent in the X-API-Key header and are encrypted at rest. The ingest key is the receiver identity each delivery is bound to; the edge keeps its spool across a revocation and resumes under a new key. The edge key is an Ed25519 key generated on the edge, whose private half never leaves it; its key id (the RFC 7638 thumbprint) is published in the key directory at /.well-known/http-message-signatures-directory, is the agent identifier on the telemetry wire, and authenticates the edge’s policy fetch. The directory’s cache age is one hour. A disconnect from the edge revokes both keys and is recorded as the edge’s own revocation.

Supplier accounts

Supplier connections and supplier usage are on Suppliers.