A2A Keys Commands¶
Issue, inspect, and revoke API keys for an A2A agent you host.
Overview¶
The superqode a2a-keys command group manages the credentials your A2A server accepts from callers. A key is signed rather than stored, so verifying one is a signature check and a clock comparison with no lookup. That matters on a host whose filesystem does not survive a deploy.
See the A2A guide for how the server uses these keys.
One secret, many keys¶
Two values do different jobs, and mixing them up is the usual cause of a key that looks correct but is rejected.
| Value | Where it lives | How many |
|---|---|---|
SUPERQODE_A2A_KEY_SECRET | On the server, never shared | One, permanent |
sqk_live_... key | Handed to a caller | One per caller |
The secret signs every key your server issues. Changing it invalidates all of them, and a key minted with a different secret fails signature verification.
Commands¶
superqode a2a-keys secret¶
Print a new signing secret to set as SUPERQODE_A2A_KEY_SECRET.
superqode a2a-keys secret
Run this once. Set the value on the server that verifies keys and keep it there.
superqode a2a-keys issue¶
Mint a key for one caller.
superqode a2a-keys issue "Platform Team" --tier standard --days 30
| Option | Default | Description |
|---|---|---|
--tier | trial | Free-form label recorded in the key |
--days | 30 | How long the key stays valid |
--test-key | off | Mint a sqk_test_ key instead of sqk_live_ |
--secret | $SUPERQODE_A2A_KEY_SECRET | Signing secret |
The key is shown once and cannot be displayed again. The command also prints the key id, which is what you need to revoke it later.
The tier is recorded on the key and surfaced to the executor, but the server does not currently branch on its value. Treat it as an attribution label.
superqode a2a-keys verify¶
Check whether a key would be accepted right now.
superqode a2a-keys verify sqk_live_...
Reports the label, tier, key id, and remaining validity, or the reason the key was rejected.
superqode a2a-keys status¶
Show whether this environment can issue and verify keys.
superqode a2a-keys status
Reports whether a signing secret is configured and how many key ids are revoked.
Revoking a key¶
Add its key id to SUPERQODE_A2A_REVOKED_KEYS on the server, comma separated. No code change or redeploy of the application is required.
SUPERQODE_A2A_REVOKED_KEYS=<key-id>,<another-key-id>
From the terminal interface¶
The same group is available as :a2a-keys inside the TUI, defaulting to status.
Related¶
Hosted skill credits¶
Use superqode a2a-keys credits --store credits.sqlite3 with grant, show, or reconcile. Grants authorize a customer, skill, finite integer credit allowance, expiry and concurrency. Signed keys authenticate separately. Reconciliation requires --charged and --reason and persists an audit record. See hosted task credits for examples.
superqode a2a-keys credits grant¶
Pass the group's --store, a customer, --credits, repeatable --skill, --days, and --max-parallel. Grants add to the balance and set current entitlements.
superqode a2a-keys credits show¶
Pass the group's --store and customer to display the balance, reserved credits, expiry, skill list, and available allowance.
superqode a2a-keys credits reconcile¶
Pass the group's --store, customer and task ID, plus --charged and a nonempty --reason. The charge must fit the original reservation. Repeating the same settlement is idempotent; a conflicting amount is rejected.