---
title: "Authentication"
description: "Reference for the auth.conf configuration file and the authentication endpoints."
stack: "Community Stack (open source) — version 1.1.1"
stack_version: "1.1.1"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/wallet2/configurations/config-files/auth
generated: 2026-10-01
---
# 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](https://docs.walt.id/community-stack/wallet2/configurations/config-files/features.md) to require email/password login and enforce that an account only accesses its own wallets.

**Note:**

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`.

```hocon
# 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.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/register` | POST | Register a new account |
| `/auth/emailpass` | POST | Log in with email + password |
| `/auth/logout` | POST | Invalidate the current token |
| `/auth/account` | GET | Get the authenticated account (id, email, wallet IDs) |
| `/auth/account/wallets` | GET | List wallets owned by the account |
| `/auth/account/wallets/{walletId}` | POST | Link a wallet to the account |

### Register

**Option: CURL**

**Endpoint:** `POST /auth/register`

##### Example Request

```bash
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

```json
{ "accountId": "b2c3d4e5-..." }
```

### Log In

**Option: CURL**

**Endpoint:** `POST /auth/emailpass`

##### Example Request

```bash
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:

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

**Note:**

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