Authentication

Every Wallet API request uses an HTTP Bearer credential:

Authorization: Bearer <credential>

Naven API credential

Your manually provisioned API credential begins with naven_api_. It is a server-side management credential with access to every wallet created for your application.

Use it with:

GET    /v1/wallets
POST   /v1/wallets
GET    /v1/wallets/:walletId
GET    /v1/wallets/:walletId/credentials
POST   /v1/wallets/:walletId/credentials
DELETE /v1/wallets/:walletId/credentials/:credentialId

During early access, contact the Naven team if this credential must be rotated or revoked.

Wallet credential

A wallet credential begins with naven_wallet_ and resolves to exactly one wallet. It is intended for an agent or isolated application runtime.

Use it with:

GET  /v1/wallets/me
POST /v1/wallets/me/pay-and-call

A wallet credential cannot list other wallets or manage credentials. It can authorize repeated x402 payments from its wallet, subject to the maxPayment constraint supplied on each call. Per-call limits are not cumulative spending limits.

Secret handling

Full credentials are returned only when they are created. Naven stores a one-way keyed hash, so a lost credential cannot be retrieved.

• Store credentials in a secrets manager or encrypted environment configuration.
• Never commit credentials to source control.
• Never expose the Naven API credential in frontend or mobile application code.
• Give each runtime a separate wallet credential when independent revocation is useful.
• Set expiresAt when a runtime needs temporary access.
• Revoke a credential immediately when a runtime is retired or compromised.

Create a wallet credential

curl https://api.naven.network/v1/wallets/$WALLET_ID/credentials \
  --request POST \
  --header "Authorization: Bearer $NAVEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "production-runtime",
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }'

The response includes secret once. Store it before continuing.

Revoke a wallet credential

curl "https://api.naven.network/v1/wallets/$WALLET_ID/credentials/$CREDENTIAL_ID" \
  --request DELETE \
  --header "Authorization: Bearer $NAVEN_API_KEY"

Revocation is immediate. Requests using the revoked wallet credential return 401 Unauthorized.