#User Authentication and Session Management

The wallet API offers various endpoints for managing user authentication and sessions. Users can create accounts using a standard email and password, an OIDC provider such as Keycloak, or Web3 wallets like Ethereum, Tezos, Flow, Near, Polkadot, and Algorand. Additionally, if you have a custom OIDC authentication solution that provides JWT session tokens, you can use those tokens directly to log in users without having to use any of the previously mentioned onboarding options.

#Storage

The wallet api uses a local database to store user accounts and session information. Secrets are encrypted using Argon2.

#Methods of Authentication

The Wallet API by default employees cookie-based authentication, as it simplifies the user experience by automatically handling the creation and renewal of cookies.

In specific scenarios where cookies may not be practical or permitted, the Wallet API also supports the Bearer token authentication method. However, here you need to manage acquiring, storing, and appending tokens to every request yourself.

We strongly advise using cookie-based authentication wherever feasible and only use Bearer tokens when necessary.

#Cookie-based Authentication

Cookie-based authentication is the default authentication method for the Wallet API. It is the simplest and most convenient method of authentication, as it automatically handles the creation and renewal of cookies.

By calling the /auth/login endpoint, the Wallet API will create a cookie containing a session token. This token is then used to authenticate the user for all subsequent requests.

By calling the /auth/logout endpoint, the Wallet API will delete the cookie containing the session token. Therefore, the user will no longer be authenticated for subsequent requests.

You can find a full list of endpoints for user authentication and session management here.

#Bearer Token Authentication

Bearer token authentication is an alternative authentication method for the Wallet API. It is more complex than cookie-based authentication, as it requires you to manage acquiring, storing, and appending tokens to every request yourself.

By calling the /auth/login endpoint, the Wallet API will return a session token. This token is then used to authenticate the user for all subsequent requests.

Response

{
  ...
  "token": "C6H7v0fjls5diXT2WX5JL7KnsEZnAysZqFjDirsNoIY",
  ...
}

By all subsequent requests, you need to append the token to the Authorization header. The token is appended as follows:

{
  "header": {
    "Authorization": "Bearer <token>"
    
    //  or

    "waltid-authorization": "Bearer <token>"
  }
}

You can find a full list of endpoints for user authentication and session management here.

#Authentication Strategies

Below you find a list of all the different authentication options you can enable for your users to secure their wallet accounts.

• Email/Password Auth - Classical email password authentication.
• OIDC Provider Auth - Connect your OIDC provider, e.g. Keycloak or Auth0 , to authenticate users.
• OIDC Unique Subject Auth - Self-manage authentication, only provide a valid JWT for auth.
• Web3 Auth - Authentication via web3 accounts from Ethereum, Tezos, Flow, Polkadot and others.