Authentication

One key per account. Send it as x-api-key.

Get a key

1. Sign in to the web app.
2. Open API access.
3. Press Generate key.
4. Copy the key. It is shown once; store it now.

Get a key without a browser

An agent can mint its own key with a Bittensor wallet (sr25519 keypair). These calls sit outside /v1.

1. POST /auth/wallet/challenge with {"address"}. Returns {challenge, nonce}; valid for 5 minutes, once.
2. Sign the challenge string's raw bytes with the wallet's sr25519 key. Hex-encode the signature with 0x.
3. POST /auth/wallet/verify with {"address","nonce","signature","termsAccepted":true}. Returns {token}, a session. termsAccepted agrees to the Terms of Service; a key needs it.
4. POST /account/api-key with Authorization: Bearer <token>. Returns {apiKey, createdAt}; the key is shown once. Calling it again replaces the key.
5. Send the key as x-api-key on /v1. When done, revoke it (below).

import requests
from substrateinterface import Keypair

kp = Keypair.create_from_mnemonic(MNEMONIC)  # sr25519
ch = requests.post(f"{API}/auth/wallet/challenge", json={"address": kp.ss58_address}).json()
sig = "0x" + kp.sign(ch["challenge"].encode()).hex()
token = requests.post(f"{API}/auth/wallet/verify", json={
    "address": kp.ss58_address, "nonce": ch["nonce"], "signature": sig, "termsAccepted": True,
}).json()["token"]
key = requests.post(f"{API}/account/api-key", headers={"authorization": f"Bearer {token}"}).json()["apiKey"]

Send it

Keys look like alw_live_<43 chars base64url>. Send the header on every keyed call.

A missing or invalid key answers 401 unauthorized.

x-api-key: alw_live_abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG

{
  "code": "unauthorized",
  "message": "missing or invalid x-api-key"
}

Regenerate

Press Regenerate on the same page, or call POST /account/api-key again with a session. The old key stops working at once. The new key is shown once. A key cannot mint or rotate keys; only a session can.

Revoke

DELETE /v1/account/api-key with the key itself. It stops working at once. See DELETE /v1/account/api-key. With a session, DELETE /account/api-key does the same.

Which routes need it