Web3 Authentication

The wallet-api lets users create and secure their account by leveraging web3 authentication. Based on the latest standards, like Login With Ethereum.

Supported Blockchains

  • Ethereum

Enabling Web3 Authentication feature in the wallet-api

To enable the web3 authentication feature in the wallet-api, you need to set the following features in the _features.conf file :

enabledFeatures = [
  # external-signature-endpoints,
  # trusted-ca,
  # entra,
  ktor-authnz,
  # dev-mode
  # ...
  ]
  disabledFeatures = [
   auth   # legacy auth
]

Configure the auth flow in ktor-authnz.conf file :

# Configure the Auth Flow (refer to: waltid-ktor-authnz)
authFlow = {
    method: web3
    expiration: "7d" # optional: Set expiration time for login tokens, e.g. a week
    ok: true # Auth flow ends successfuly with this step

Authentication Flow

  1. Client Requests Nonce
    • Client calls GET /web3/nonce
    • Server generates a random nonce and returns it as a JWT
  2. Client Signs Message
    • Client uses their Ethereum wallet to sign the nonce
    • Message is formatted according to EIP-191 standard
  3. Client Submits Signature
    • Client sends the signed message , the challenge and public key to POST /web3/signed
    • Server verifies the signature and authenticates the user
  4. Server Authentication
    • Server recovers the public key from the signature
    • Verifies the recovered address matches the provided address
    • Creates or retrieves user account
    • Issues session token

Generate a new nonce for web3 authentication

To login with a web3 wallet, you need to generate a nonce first. The nonce is a random string that is used to sign a message and verify the signature.:

CURL

API Reference

curl -X 'POST' \
  'http://0.0.0.0:7001/wallet-api/auth/account/web3/nonce' \
  -H 'accept: */*'

Example Response

eyJhbGciOiJFZERTQSJ9.eyJub25jZSI6IjB4YjI1NzJhZWE2ODEyYmM4NjE2MDgyN2M3NmRmMjA3ZWVlNWNjMGVjNzQ4MmRlZjFhMmYxMTFiZTYxZGIzNjI3NyIsImV4cCI6MTczNzA2MjAyMH0.bQYGos3ZYA0POd5Dibvg7-NDZldVyReIW_0BsdDjVDpu0Tz1DJR9ZTpAuQlanC5hPgLB1yRua9_FPJ-0lokZCw

Login

CURL

API Reference

curl -X 'POST' \
 'http://0.0.0.0:7001/wallet-api/auth/account/web3/signed' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "challenge": "eyJhbGciOiJFZERTQSJ9.eyJub25jZSI6IjB4YTgzNzI1M2U3ZDdmNjhkMGI5ODM2ZWMzNjlkZWE0MmMyYTFmMDg0ZWU3NDhjYTM0YTc4YTI2OTY4YTJiY2Q1NiIsImV4cCI6MTczNzA2MjE5OX0.DJAb5AgZO-Qgxe7nTkkt7qVWlM_bhQcpM7ZkD9HSqIQ81DAIm-OpOjv0Y56R6lmOVy82sVpHg4g7RUofTzieCg",
  "signed": "0x132463eab627a8ba10f0fc87871b48cb193ada7cab01ff68ed3627ab5b7268c64d3fe7172f58634ecb1412ff0084c70611dbe30c0cdc99528e2e06437a4056ae1c",
  "publicKey": "0xec57a39eb7e46728c143f8c1a0eb6d0fb77c814d"
}'

Body Parameters

{
  "challenge": "string",
  "signed": "string",
  "publicKey": "string"
}
  • challenge: String - The nonce generated in the previous step.
  • signed: String - The signed message by the user.
  • publicKey: String - The public key of the user's wallet.

Example Response
Now a session is automatically created for web3 authentication. For Bearer Token Authentication, the token returned must be provided in the header for each request that needs authentication. Refer to the overview section for more details.

{
  "session_id": "0211b04c-cb5b-4b56-8a49-eaa63b4fdfe8",
  "status": "OK",
  "token": "eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiI1MmIyZDQ2Zi0wNzQ0LTQ1YTgtOTIwNS1jZjdjYTMyODhkMzEiLCJzZXNzaW9uIjoiMDIxMWIwNGMtY2I1Yi00YjU2LThhNDktZWFhNjNiNGZkZmU4IiwiZXhwIjoxNzM3NjY2ODkxfQ.34-eydmcP7Vc8GJTsvqm8ofEnp2Ch_ZaZJHqYJO8edeBBvAoLB06YtWCLz2eDbLAxPyBkQwJOtJ6DPv0j1b3Cg",
  "expiration": "2025-01-23T21:14:51.542977200Z"
}
Email/Password AuthX.509 Certificate