Skip to main content

JWT Configuration

Bellamy Book uses JWT (JSON Web Tokens) for authentication. You must set a secret key and optionally issuer/audience. If the secret is wrong or missing, login and API auth will fail.

Step 1: Generate a secret​

Generate a strong random secret (at least 32 characters). For example:

openssl rand -base64 64

Use the output as JwtSettings__Secret (you can trim to 32+ chars if needed; 64 is recommended).

Step 2: Set in .env​

In your .env (in the folder that contains docker-compose.yml):

VariableExampleDescription
JwtSettings__Secret(output of openssl rand -base64 64)Required. Secret used to sign and validate tokens. Must be the same on every API instance.
JwtSettings__Issuer${API_PUBLIC_URL} or https://api.yourdomain.comIssuer of the token. Should match your API’s public URL.
JwtSettings__Audience${API_PUBLIC_URL} or https://api.yourdomain.comIntended audience. Usually same as Issuer.
JwtSettings__ExpirationMinutes15Access token lifetime in minutes. 15 is a good balance; 30 reduces refresh calls.

Example:

JwtSettings__Secret=your_base64_secret_from_openssl
JwtSettings__Issuer=${API_PUBLIC_URL}
JwtSettings__Audience=${API_PUBLIC_URL}
JwtSettings__ExpirationMinutes=15

Using ${API_PUBLIC_URL} keeps issuer/audience in sync with your domain.

Important​

  • Do not commit JwtSettings__Secret to version control. Keep it in .env or a secrets manager.
  • Rotate the secret periodically; when you do, all existing tokens become invalid and users must log in again.
  • Use one secret per environment (e.g. one for production, one for staging). Do not reuse the same secret across different deployments.

Restart after changes​

docker compose restart api

Next steps​