Skip to main content

Authentication

Two layers of authentication cover the two kinds of callers:

  1. Partner authentication: your backend, with an API key.
  2. User authentication: the cardholder, with their wallet (Sign-In with Ethereum), for actions that must be signed by the vault owner.
API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

Partner API keys​

Keys are issued per environment during onboarding and sent as a Bearer token:

curl https://api.web3card.dev/v1/users \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"

Keys can be rotated at any time from the partner dashboard. Old keys keep working for 24 hours after rotation.

Sign-In with Ethereum (SIWE)​

Vault-owner actions (withdrawals, adding wallets, changing on-chain limits) require a user session proven by a wallet signature.

POST /auth/nonce​

Generate the message the user must sign.

// Request
{ "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F" }

// Response
{
  "nonce": "kX9m2pQr",
  "message": "web3card.dev wants you to sign in with your Ethereum account…"
}

POST /auth/verify​

Verify the SIWE signature and open a user session.

// Request
{
  "walletAddress": "0x71C2a4f3b7c48d19D4a2e9Eb0cE3606eB48a3a4F",
  "signature": "0x8b4d…c91e"
}

// Response
{ "sessionToken": "w3cs_a91k…", "expiresIn": 3600 }

Send the session token alongside your API key on user-signed endpoints:

Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx
X-W3C-User-Session: w3cs_a91k…

Email verification​

POST /users/{id}/email/otp​

Send a one-time code to the user's email.

POST /users/{id}/email/verify​

// Request
{ "code": "482913" }

// Response
{ "verified": true }
Last updated on