Multi-keypair.

Code notes

The passkey is a WebAuthn credential that authenticates a browser session and nothing else — it cannot sign a storage envelope. Each signing keypair is provisioned on its own, owns its own lockers, and authorizes gateway work through the X-Nukez-Identity header plus a signature from its private key. Linking is the operation that tells the portal which already-provisioned keypairs belong to one human, so their files, status, usage and alerts render in a single view.

1. 1The portal identityThe passkey is a discoverable WebAuthn credential registered against RP_ID nukez.xyz, and the session token it produces is stored in localStorage under nukez_session_token and sent as a Bearer header on every session-gated portal read.
2. 2The signing keypairsEach keypair is provisioned separately and signs with its native scheme: Ed25519 keys base58-encode their 64-byte signatures, while secp256k1 keys sign through EIP-191 personal_sign and return 0x-prefixed hex.
3. 3What linking joinsThe link endpoints attach one or more already-provisioned keypairs to the single portal identity that your passkey created, which is what makes a merged view possible.
4. 4What linking leaves aloneEvery file in the merged list carries the pubkey of the identity that stored it, so you can tell which key owns which file, but lockers are never shared between keys and no key gains the ability to sign for another.

Code notes

A keypair can only be linked after it has completed provisioning on its own — its own developer_id and active storage, which means running POST /v1/provision/challenge and POST /v1/provision/verify for that key first. The link-pubkey call is where the precondition is enforced, and it needs no session of its own: it is the one step in this flow you can run from a bare terminal. A 404 means the key has no NukezAgent subscription yet; a 409 means it is already linked to this portal identity. A success returns the exact challenge string to sign and the unix timestamp at which it stops being valid.

1. 1Derive the public keyThe script reads the keypair file, takes its first 32 bytes as the Ed25519 seed, and base58-encodes the verify key to produce the public key that will be linked.
2. 2Request the link challengePOST /v1/portal/auth/link-pubkey takes a single field, pubkey, carries no Authorization header, and is the same endpoint the portal Keys view calls when you paste a key into its inline link form.
3. 3Handle the rejectionsA 404 means this key has not been provisioned and must complete provisioning before it can be linked; a 409 means it is already attached to this portal identity, so there is nothing left to do. The endpoint also returns 403 when the key is provisioned but its account is not active, and that case falls through to raise_for_status on the next line.
4. 4Read the challengeThe response carries the exact string to sign and an expires_at timestamp in unix seconds, which the portal Keys view renders as a live countdown while you produce the signature.

Code notes

Signing the challenge is the entire proof of control. Ed25519 signs the raw challenge bytes and base58-encodes the signature; secp256k1 signs the same string through EIP-191 personal_sign and submits 0x-prefixed hex. The request to POST /v1/portal/auth/link-pubkey/verify carries three fields — pubkey, the challenge exactly as it was issued, and the signature — and the response returns a status, a link_token, and a ready-made portal_url that already carries that token as a query parameter.

1. 1Ed25519 signatureThe challenge string is signed as raw UTF-8 bytes and the resulting signature is base58-encoded, which is the encoding the verify endpoint expects for Ed25519 keys.
2. 2secp256k1 variantAn EVM key signs the identical challenge string through EIP-191 personal_sign and submits the signature as 0x-prefixed hex, with the account address standing in for the pubkey field.
3. 3Submit the proofThe verify request body carries three fields — the pubkey being linked, the challenge exactly as it was issued, and the signature — and never carries private key material; a wrong signature comes back as 403 and a stale or mismatched challenge as 400.
4. 4link_token and portal_urlA successful verify returns status verified along with a link_token and a portal_url that already embeds it, so opening that URL is the only remaining step and there is nothing to copy by hand.

Code notes

The verify call does not complete the link, because completion requires your portal session and the terminal does not have one. Opening portal_url lands on /agent-portal with a link_token query parameter. If a session is already active the portal calls link-pubkey/complete immediately; if not, it stashes the token in sessionStorage, takes you through one passkey tap, then consumes it. Both paths end on the Keys page.

1. 1Two entry statesThe portal reads link_token from the URL on load, and it handles the signed-out case by holding the token in sessionStorage across the passkey prompt rather than discarding it.
2. 2The completing callThe portal sends the link_token to POST /v1/portal/auth/link-pubkey/complete with the Bearer session token it read from localStorage, which is exactly why this final step cannot be performed from the terminal.
3. 3OutcomesA completed link returns status linked with the full updated key set and redirects to /agent-portal/keys, a key that was already attached to this identity returns 200 with status already_linked and is treated the same way, and an invalid or already-consumed token returns 400 with a message asking you to re-run the verify step.
4. 4URL cleanupThe portal removes the link_token from the address bar on both success and failure, so a consumed token is not left sitting in the URL to be re-shared or re-submitted.

Code notes

GET /v1/portal/auth/linked-keys is the authoritative list. It returns portal_identity plus one entry per linked key carrying developer_id, pubkey, algorithm, label and linked_at. The portal Keys view renders exactly this, and falls back to showing only the pubkey from status when the endpoint is not yet live. Confirming here is worth the extra call because linking changes what you see and nothing else: every gateway request still resolves to the single key named in X-Nukez-Identity.

1. 1Session-gated readThis endpoint requires the portal session Bearer token, so it answers for the logged-in portal identity and cannot be queried from the terminal with a keypair alone.
2. 2Response envelopeThe response names the portal identity the keys are grouped under and returns them in a single keys array rather than as separate per-algorithm lists.
3. 3One entry per keyEach entry keeps its own developer_id, proving that the two keys remain distinct accounts, and reports algorithm and an ISO-8601 linked_at; label is part of the response but the Keys view does not currently render it. Rows come back ordered by linked_at, oldest first.
4. 4How the portal reads thisThe Keys view turns each entry into a row and marks the first one Primary purely as an ordering convention, while the sidebar surfaces a key-count link once the array holds more than one key. None of this changes gateway behaviour: lockers stay owned by the key that provisioned them.