Authentication Configuration

auth.conf configures email/password authentication for the Wallet API v2 auth optional feature.

By default the Wallet API v2 runs without authentication — every wallet is accessible without a token. Enable the auth optional feature to require email/password login and enforce that an account only accesses its own wallets.

Auth uses an in-memory account store in the Community Stack service. Accounts are lost on restart unless you provide a persistent account-store implementation. Wallet ownership mappings are stored through the wallet store.

File Location

waltid-services/waltid-wallet-api2/config/auth.conf

Fields

signingKey

Object — Serialized walt.id crypto key used to sign and verify JWT session tokens.

Use the same signing key on every replica so tokens issued by one instance can be verified by the others. Recommended key types are secp256r1 (ES256) or Ed25519 (EdDSA).

tokenExpiry

String — Session token lifetime as an ISO-8601 duration.

Defaults to PT24H. Examples: PT30M, PT24H, P7D.

# auth.conf
signingKey = {
  type = "jwk"
  jwk = {
    kty = "EC"
    crv = "P-256"
    x = "..."
    y = "..."
    d = "..."
  }
}
tokenExpiry = "PT24H"

Authentication Endpoints

When auth is enabled, the following endpoints are available. After logging in, pass the returned token as Authorization: Bearer {token} on every wallet request.

EndpointMethodDescription
/auth/registerPOSTRegister a new account
/auth/emailpassPOSTLog in with email + password
/auth/logoutPOSTInvalidate the current token
/auth/accountGETGet the authenticated account (id, email, wallet IDs)
/auth/account/walletsGETList wallets owned by the account
/auth/account/wallets/{walletId}POSTLink a wallet to the account

Register

CURL

Endpoint: POST /auth/register

Example Request
curl -X POST http://localhost:7006/auth/register \
  -H 'Content-Type: application/json' \
  -d '{ "email": "user@example.com", "password": "secret123" }'

Body Parameters

  • email: String (required) - The account email.
  • password: String (required) - The account password.
Example Response
{ "accountId": "b2c3d4e5-..." }

Log In

CURL

Endpoint: POST /auth/emailpass

Example Request
curl -X POST http://localhost:7006/auth/emailpass \
  -H 'Content-Type: application/json' \
  -d '{ "email": "user@example.com", "password": "secret123" }'

Body Parameters

  • email: String (required) - The account email.
  • password: String (required) - The account password.
Example Response

The response is a session object containing the bearer token. Use the token on subsequent requests:

curl http://localhost:7006/wallet \
  -H 'Authorization: Bearer {token}'

New wallets created while authenticated are automatically linked to your account, so GET /wallet and GET /auth/account/wallets return only your own wallets.

Last updated on July 28, 2026
PersistenceDev Mode