Passkey setup.

Code notes

Portal enrollment starts from a keypair, not an email address. The public key is the identity that the service issues a challenge against, and the private key is the only thing that can answer it. Either curve is accepted: an Ed25519 key in the 64-byte Solana JSON array format, or a secp256k1 EVM key stored as an address and private key. The portal itself lives at https://portal.nukez.xyz/agent-portal and is backed by the service at https://agent.nukez.xyz. If you already hold a keypair, skip this step and go straight to the challenge.

1. 1Install the dependencies for your curveEd25519 signing needs pynacl and base58, while secp256k1 signing needs eth-account. Both paths use httpx for the two provisioning calls, and the passkey step itself requires a browser with a platform authenticator or a security key.
2. 2Generate an Ed25519 keypairThe file written here is the 64-byte concatenation of the signing seed and the verify key, which is the same JSON array layout the Solana CLI uses. The printed base58 verify key is the value you send as pubkey in every provisioning call.
3. 3Generate a secp256k1 keypairAccount.create() produces an EVM key, and the file stores the checksummed address alongside the private key. The 0x-prefixed address is what goes in the pubkey field; there is no separate registration format for EVM identities.
4. 4Only the public half is ever transmittedNukez receives the public key and signatures computed over challenge strings. The private key is never uploaded during provisioning, passkey registration, or later key linking, so the key file you just wrote is the only copy that exists.

Code notes

Provisioning is a two-call challenge-response against https://agent.nukez.xyz. POST /v1/provision/challenge returns a message to sign; POST /v1/provision/verify checks the signature, creates the developer record, and returns a ready-made portal_url with a register_token embedded in the query string. Nothing about the passkey exists yet at this point: the keypair is what proves who you are, and the portal URL is the bridge from that proof to a browser credential.

1. 1Load the key and derive the identityThe first 32 bytes of the saved array are the signing seed; the base58 encoding of the derived verify key is the pubkey the service knows you by. For an EVM key this block is replaced by Account.from_key(), and pubkey becomes the 0x address.
2. 2Request the provisioning challengeThe response carries a nonce, a message, and an expires_at. The message has the form nukez-provision:{nonce}:{timestamp}, where the nonce is 16 random bytes rendered as 32 hex characters, and it is only valid for 120 seconds, so sign and submit it in the same script run rather than pasting it around.
3. 3Sign the message string, not the nonceThe bytes to sign are the UTF-8 encoding of the message field exactly as returned, including the nukez-provision prefix and the timestamp. Ed25519 signatures are base58-encoded; a hex or base64 encoding is rejected by the verifier.
4. 4Verify returns the developer record and the portal URLThe request sends the pubkey, the original nonce, and the signature. The response contains developer_id, status, owner_pubkey, a registration_token, and a portal_url that already has the token in its query string. Save developer_id and portal_url before the script exits.

Code notes

Opening portal_url is the entire registration step. The portal reads register_token from the query string and renders the registration gate instead of the Connect button, then calls the options endpoint, runs the WebAuthn ceremony, and posts the result back. The credential is created with resident key REQUIRED, so it is discoverable and can be found later without a username, and user verification REQUIRED, so a biometric or PIN check is mandatory on every use. The relying party id is nukez.xyz and the expected origin is https://portal.nukez.xyz.

1. 1Open the URL provisioning returnedThe portal gate branches on the presence of register_token: with the parameter it renders the registration view, without it the Connect button. Registration is triggered automatically when that view mounts, so the biometric prompt appears without an extra click.
2. 2Registration options are authorized by the register_tokenThe options call carries the register_token as its Bearer credential, which is why no session exists yet. The relying party id is nukez.xyz, user.id is the base64url encoding of the developer_id, user.name is the truncated public key, and displayName is always Nukez Developer.
3. 3Discoverable credential with mandatory user verificationresidentKey is required, not preferred, so the credential is stored on the authenticator and can be discovered at login with no identifier typed in. userVerification is required, attestation is none, and excludeCredentials lists any passkeys already registered to this developer_id so the same authenticator is not enrolled twice; on a first registration it is empty.
4. 4The browser creates the credential and the server opens a sessionThe attestationObject and clientDataJSON are posted back with the same Bearer token, and the server verifies them against rp id nukez.xyz and origin https://portal.nukez.xyz. The response includes a session_token, developer_id, and expires_at, so registration signs you in without a second prompt, and the register_token is deleted after this single use.

Code notes

The register_token in portal_url lives for ten minutes. Once it lapses the options call answers 401 and the prompt never fires. Rather than re-running provisioning, prove control of the same keypair again through the portal challenge pair: POST /v1/portal/auth/challenge returns a fresh string to sign, and POST /v1/portal/auth/verify-keypair exchanges the signature for a new registration_token. This route requires the developer record to be active already, because the challenge call answers 403 while the status is still pending_payment. This example signs with a secp256k1 EVM key to show the other half of the signing contract.

1. 1Recognise an expired registration tokenA register_token is good for ten minutes and is consumed on first successful use. Once it has lapsed the register options and complete endpoints both answer 401 with an invalid-or-expired message, and the portal shows the error instead of the biometric prompt.
2. 2Request a portal registration challengeThis endpoint returns a challenge string and an expires_at 120 seconds out, and the string carries the purpose inline as nukez-stepup:portal_registration. A 404 means the pubkey has no developer record yet, and a 403 means the record exists but its status is not active, so provisioning or payment still has to finish first.
3. 3Sign with secp256k1 or Ed25519encode_defunct produces the EIP-191 personal_sign digest, and the resulting signature is submitted as 0x-prefixed hex. The commented line is the Ed25519 alternative over the identical string: base58 encoding of the raw 64-byte signature.
4. 4Exchange the signature for a new tokenThe request echoes the exact challenge string alongside the pubkey and signature; a mismatch is rejected with 400 rather than silently ignored. The response returns status verified plus a registration_token good for another ten minutes, and the last line prints the ready-to-open portal URL that carries it.

Code notes

After registration the portal URL needs no parameters. With no register_token present the gate renders the Connect button, which requests authentication options and calls navigator.credentials.get(). Because the credential is discoverable, the options carry an empty credential id list and the authenticator identifies you from the passkey it already holds. A successful assertion returns a bearer session token that the portal keeps in localStorage and attaches to every subsequent portal request.

1. 1Later visits need no query parametersThe bare portal URL is all that is required once a passkey exists. The gate only renders the registration view when register_token is present, so every subsequent visit lands on the Connect button instead.
2. 2Login options are unauthenticated and hold no credential idsThis call carries no Authorization header because the assertion itself is the proof. The relying party id is nukez.xyz, user verification stays required, and allowCredentials comes back empty by design: the authenticator finds the discoverable credential and returns the developer_id as userHandle, which is how the server resolves the account.
3. 3The assertion is exchanged for a sessionThe signed assertion is posted back and verified against the stored challenge and the expected origin https://portal.nukez.xyz. The response returns status authenticated together with session_token, developer_id, and an expires_at expressed in unix seconds.
4. 4The session lives in localStorage with an explicit expiryThree keys are written: nukez_session_token, nukez_developer_id, and nukez_session_expires. The token is sent as an Authorization Bearer header on every portal request, the default lifetime is 86400 seconds, and both a passed expiry and any 401 response clear all three keys and return the portal to the Connect button.