---
title: "Overview"
description: "User authentication and session management in the walt.id wallet API."
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/wallet/authentication/overview
generated: 2026-07-20
---
# User Authentication and Session Management

**Info:**

We have recently added a new authentication strategy to the wallet which leverages our own [`waltid-ktor-authnz` library](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/auth/waltid-ktor-authnz).
We recommend using this new authentication strategy if possible for all future developlemts. It offers a more production ready solution of our open source wallet backend including authentication methods for:
* Email/Password Auth
* OIDC Auth

You can find more information about the new authentication strategy [here](https://docs.walt.id/community-stack/wallet/authentication/new-auth.md).

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](https://wallet.demo.walt.id/swagger/index.html#/Authentication).

### 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**

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

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

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

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

You can find a full list of endpoints for user authentication and session
management [here](https://wallet.demo.walt.id/swagger/index.html#/Authentication).

## 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](https://docs.walt.id/community-stack/wallet/authentication/email-password-auth.md) - Classical email password authentication.
- [OIDC Provider Auth](https://docs.walt.id/community-stack/wallet/authentication/jwt-oidc/oidc.md) - Connect your OIDC provider, e.g. Keycloak or Auth0 , to authenticate users.
- [OIDC Unique Subject Auth](https://docs.walt.id/community-stack/wallet/authentication/jwt-oidc/oidc-unique-sub-auth.md) - Self-manage authentication, only provide a valid JWT for auth.
- [Web3 Auth](https://docs.walt.id/community-stack/wallet/authentication/web3-auth.md) - Authentication via web3 accounts from Ethereum, Tezos, Flow, Polkadot and others.