Configure authentication settings per tenant in HelloJohn — allowed auth methods, MFA policy, allowed email domains, OAuth apps, and JWT customization.

Every tenant in HelloJohn has its own auth configuration. This lets you customize the authentication experience per customer — require MFA for enterprise customers, restrict login to specific email domains, or configure a customer's own OAuth credentials.

Get tenant auth config

GET /v2/admin/tenants/{tenantId}/auth/config
Authorization: Bearer $ADMIN_TOKEN

{
  "tenant_id": "ten_01HX...",
  "allowed_auth_methods": ["email_password", "google", "magic_link"],
  "mfa_required": false,
  "mfa_methods": ["totp", "webauthn", "backup_codes"],
  "allowed_email_domains": [],
  "password_policy": {
    "min_length": 8,
    "require_uppercase": false,
    "require_numbers": false,
    "require_symbols": false
  },
  "session_config": {
    "access_token_ttl": 900,
    "refresh_token_ttl": 2592000
  },
  "sso_enabled": false,
  "sso_required": false
}

Updating tenant auth config

PATCH /v2/admin/tenants/{tenantId}/auth/config
Authorization: Bearer $ADMIN_TOKEN
Content-Type: application/json

{
  "mfa_required": true,
  "allowed_email_domains": ["acme.com", "acme-corp.com"],
  "password_policy": {
    "min_length": 12,
    "require_uppercase": true,
    "require_numbers": true
  }
}

Only the fields you provide are updated. Omitted fields keep their current values.

Restricting auth methods

Allow only specific authentication methods for a tenant:

{
  "allowed_auth_methods": ["email_password", "google"]
}

Valid values: email_password, magic_link, google, github, apple, microsoft, discord, gitlab, twitter, api_key, sso

Restricting by email domain

Force users to register/login with specific email domains:

{
  "allowed_email_domains": ["acme.com"]
}

When set, HelloJohn rejects registration and login for emails outside the allowed domains. Useful for enterprise tenants where you want to ensure only company employees can access.

This restriction applies to email/password and magic link auth. OAuth login is restricted to the email returned by the OAuth provider.

Password policy

Configure per-tenant password strength requirements:

{
  "password_policy": {
    "min_length": 12,
    "max_length": 128,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_symbols": false,
    "prevent_common_passwords": true,
    "password_history": 5
  }
}

password_history: 5 prevents users from reusing their last 5 passwords.

Per-tenant OAuth apps

Configure a customer's own OAuth credentials (so they see "Sign in with Google" using their own Google OAuth app, not yours):

POST /v2/admin/tenants/{tenantId}/oauth/providers
Content-Type: application/json

{
  "provider": "google",
  "client_id": "customer-client-id.apps.googleusercontent.com",
  "client_secret": "customer-secret"
}

When this is set, the tenant's OAuth flow uses these credentials instead of the instance-level credentials.

JWT customization per tenant

Add custom claims to JWTs for this tenant:

{
  "jwt_claims": {
    "static": {
      "app_name": "Acme Portal",
      "environment": "production"
    },
    "from_user_metadata": ["plan", "salesforce_id"],
    "from_tenant_metadata": ["tier"]
  }
}

The resulting JWT will contain:

{
  "sub": "usr_01HX...",
  "tenant_id": "ten_01HX...",
  "app_name": "Acme Portal",
  "environment": "production",
  "plan": "enterprise",
  "tier": "premium"
}

Session TTL override

Override the global session TTL for high-security tenants (shorter) or internal tools (longer):

{
  "session_config": {
    "access_token_ttl": 300,
    "refresh_token_ttl": 86400
  }
}

Per-tenant Configuration