Configure Alphabet: database, cache, and JWT settings

Configure Alphabet’s database provider, cache backend, JWT tokens, email, SMS, CORS, and lockout settings through appsettings.json.

All runtime configuration for Alphabet lives in appsettings.json at the API gateway. You can override any value with environment-specific files (appsettings.Development.json, appsettings.Production.json), environment variables, or .NET user secrets. The sections below document every key you are likely to need as a consumer of this API.

Never commit real secrets — database passwords, JWT secret keys, SMTP API keys, or Twilio credentials — to source control. Use dotnet user-secrets, environment variables, or a secrets manager such as Azure Key Vault or AWS Secrets Manager in any non-local environment.

---

Database provider

The Database section controls which persistence backend EF Core uses.

"Database": {
  "Provider": "SqlServer",
  "ConnectionString": "Server=localhost;Database=AlphabetDb;..."
}

Database.Provider · string · required

Selects the EF Core database provider. Accepted values:

Value	Provider
SqlServer	Microsoft SQL Server via UseSqlServer
PostgreSql or Postgres	PostgreSQL via UseNpgsql
InMemory	In-memory database — useful for local development without Docker

Database.ConnectionString · string · required

The ADO.NET connection string for SQL Server or PostgreSQL. Not used when Provider is InMemory.

To switch from SQL Server to PostgreSQL:

1. Set Database.Provider to PostgreSql.
2. Update Database.ConnectionString with your PostgreSQL connection string.
3. Apply any pending migrations using the EF Core CLI or your deployment pipeline.
4. Restart the API.

---

Cache provider

The Cache section controls caching behavior across the application.

"Cache": {
  "Provider": "Memory",
  "RedisConnectionString": "localhost:6379",
  "DefaultExpirationMinutes": 5
}

Cache.Provider · string · required

Selects the cache backend. Accepted values:

Value	Description
Memory	In-process memory cache. No external dependency required.
Redis	Distributed Redis cache. Requires a reachable Redis instance.

Cache.RedisConnectionString · string

Connection string for Redis, e.g. localhost:6379. Only used when Provider is Redis.

Cache.DefaultExpirationMinutes · integer

How long cached entries are kept before expiring. Default: 5.

To switch to Redis: set Cache.Provider to Redis, set Cache.RedisConnectionString, ensure Redis is reachable, and restart the API. Application code does not change — the cache backend is swappable without modifying any feature code.

---

JWT settings

The Jwt section controls how access and refresh tokens are issued and validated.

"Jwt": {
  "Issuer": "Alphabet",
  "Audience": "Alphabet.Clients",
  "SecretKey": "ReplaceThisWithASecretFromUserSecretsOrVault123!",
  "AccessTokenExpiryMinutes": 15,
  "RefreshTokenExpiryDays": 7,
  "MfaTokenExpiryMinutes": 5,
  "SigningAlgorithm": "HS256"
}

Field	Default	Description
Issuer	Alphabet	The iss claim value in every token. Must match the value your client validates against.
Audience	Alphabet.Clients	The aud claim value.
SecretKey	(placeholder)	The HMAC signing key. Must be at least 32 characters and treated as a secret.
AccessTokenExpiryMinutes	15	How long an access token remains valid before clients must refresh.
RefreshTokenExpiryDays	7	How long a refresh token can be used to obtain new access tokens.
MfaTokenExpiryMinutes	5	Validity window for short-lived MFA challenge tokens.
SigningAlgorithm	HS256	JWT signing algorithm. HMAC-SHA256 by default.

The default SecretKey in appsettings.json is a placeholder. Replace it before deploying. Store the real value in dotnet user-secrets locally and in a secrets manager or environment variable in production:

dotnet user-secrets set "Jwt:SecretKey" "your-real-secret-here"

---

Account lockout

The LockoutSettings section controls how Alphabet responds to repeated failed login attempts.

"LockoutSettings": {
  "MaxFailedAttempts": 5,
  "LockoutDurationMinutes": 5
}

LockoutSettings.MaxFailedAttempts · integer

Number of consecutive failed login attempts before the account is locked. Default: 5.

LockoutSettings.LockoutDurationMinutes · integer

How long (in minutes) an account stays locked after the threshold is reached. Default: 5.

---

Email settings

The EmailSettings section configures the SMTP sender used for transactional emails such as email confirmation and password reset.

"EmailSettings": {
  "FromEmail": "[e-mail]",
  "FromName": "Alphabet",
  "SmtpServer": "smtp.sendgrid.net",
  "SmtpPort": 587,
  "ApiKey": ""
}

EmailSettings.FromEmail · string · required

The address that appears in the From field of outgoing emails.

EmailSettings.FromName · string

The display name shown alongside FromEmail.

EmailSettings.SmtpServer · string · required

Hostname of the SMTP relay. The default points to SendGrid’s SMTP endpoint.

EmailSettings.SmtpPort · integer

SMTP port. Default: 587 (STARTTLS).

EmailSettings.ApiKey · string

API key for your SMTP provider. Store this in user secrets or an environment variable — do not commit it.

---

SMS settings

The SmsSettings section configures outbound SMS through Twilio.

"SmsSettings": {
  "AccountSid": "",
  "AuthToken": "",
  "FromNumber": "[phone]"
}

SmsSettings.AccountSid · string · required

Your Twilio Account SID. Store in user secrets or an environment variable.

SmsSettings.AuthToken · string · required

Your Twilio Auth Token. Store in user secrets or an environment variable.

SmsSettings.FromNumber · string · required

The Twilio phone number messages are sent from, in E.164 format (e.g., [phone]).

---

CORS

The Cors section controls which origins the API accepts cross-origin requests from.

"Cors": {
  "AllowedOrigins": [
    "https://localhost:3000"
  ]
}

Cors.AllowedOrigins · string[] · required

Array of allowed origins. The default allows only https://localhost:3000. Add your production frontend origin before deploying:

"Cors": {
  "AllowedOrigins": [
    "https://localhost:3000",
    "https://app.yourdomain.com"
  ]
}

The CORS policy allows any header and any HTTP method from the listed origins and permits credentials (cookies).

---

Frontend URLs

The FrontendUrls section controls the base URLs embedded in email links sent to users.

"FrontendUrls": {
  "ConfirmEmail": "https://localhost:3000/confirm-email",
  "ResetPassword": "https://localhost:3000/reset-password"
}

FrontendUrls.ConfirmEmail · string · required

The URL your frontend handles for email confirmation. Alphabet appends a token query parameter when generating the confirmation link.

FrontendUrls.ResetPassword · string · required

The URL your frontend handles for password resets. Update this to your production domain before going live.

These values must point to pages in your frontend application that know how to read the token from the query string and call the corresponding Alphabet API endpoint to complete the action.