API keys and authentication

A customer API key acts as the supanova profile that created it. Each key has read access; trade is an additional scope. Keep read integrations and trading integrations on separate keys.

Choose a credential

Credential	What it does
No credential	Public routes that permit anonymous access, including token discovery and app configuration.
`X-API-Key` with `read` scope	Supported public data and the key owner's portfolio, activity, operations, valuation, and order status.
`X-API-Key` with `read` and `trade` scopes	The supported quote and order routes, with signed requests and Party authorization.
`Authorization: Bearer …`	A signed-in customer session for account management and supported interactive product flows.

Never send Authorization and X-API-Key together. The API rejects the combination with AMBIGUOUS_CREDENTIALS.

An API key is accepted only when the operation declares x-api-key-scope in OpenAPI. It is not a substitute for a session on every route. In particular, keys do not authorize withdrawal, transfer, or launch routes.

Create a read key

Use API-key setup in Launchpad, or call the key-management endpoint with your signed-in session token:

curl --fail-with-body --silent --show-error \
  'https://launch-api.supanova.app/api/v1/me/api-keys' \
  -H "Authorization: Bearer $SUPANOVA_SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Market reader","scopes":["read"],"ipAllowlist":[],"expiresInDays":30}'

The response contains key metadata in key and the full credential in secret. Save secret securely at creation. It cannot be retrieved later.

Mainnet keys start with sn_live_. Keys on other networks start with sn_test_. The complete format is sn_live_<id>_<secret> or sn_test_<id>_<secret>. The key ID is 12 lowercase base32 characters; it is safe to use for identifying a key in logs. The secret is not.

Authorize a trade key

Trade access requires two separate keys: the customer API credential and an Ed25519 signing key pair. The API stores the signing public key. Keep the signing private key with your trading service.

Generate an Ed25519 pair. The app can generate it in the browser and provide a one-time PKCS#8 PEM private-key download.
With your session token and the app's Origin, call POST /api/v1/me/api-keys/trade-authorizations with walletConnectionId and signingPublicKey.
The connected Party's wallet signs the returned signingRequest.params.hash using signHash. The authorization challenge lasts five minutes and can be consumed once.
Call POST /api/v1/me/api-keys with name, scopes: ["read", "trade"], signingPublicKey, ipAllowlist, and the returned authorization proof: challengeId, message, signature, and publicKey.

The resulting key may trade only for the Party that authorized it. Using another wallet connection, even one on the same account, returns API_KEY_PARTY_NOT_AUTHORIZED.

A trade key authorizes API requests. An externally controlled Party still needs its own ledger-signing path to submit a prepared order. A Party whose key is held in the Supa wallet through Privy cannot sign headlessly; use the interactive app flow for that wallet.

Send a key

X-API-Key: <your-customer-api-key>

Trade requests additionally use X-API-Timestamp, X-API-Signature, an Idempotency-Key, and optionally X-API-Recv-Window. Follow request signing for the exact byte format.

Expiry and IP restrictions

Setting	Rule
Active keys	Up to 10 per account by default.
Expiry	Optional expiry from 1 to 365 days.
Trade key without an IP allowlist	Expires after at most 90 days.
IP allowlist	Up to 16 addresses or networks. IPv4 networks must be `/16` or narrower; IPv6 networks `/48` or narrower. Use network addresses for CIDRs.
Network	A key is valid only on the network where it was created, including between different test networks.
Revocation	Takes effect across servers within five seconds.

IPv4-mapped and IPv4-compatible IPv6 ranges are rejected. When using a proxy or server platform, allow the public egress IP that the API will see.

List, rotate, and revoke

GET /api/v1/me/api-keys returns your keys and the configured limits. DELETE /api/v1/me/api-keys/{keyId} revokes a key. Both require a customer session, not an API key.

To rotate a read key, create its replacement, update the integration, verify a read, and revoke the old key. A replacement trade key needs a new authorization for its signing public key. Revoke a compromised key immediately and replace its signing material if that material may also have been exposed.

Choose a credential#

Create a read key#

Authorize a trade key#

Send a key#

Expiry and IP restrictions#

List, rotate, and revoke#