Get the identity settings

GET /v1/identity-settings · permission identity-settings:read

Returns the environment's username settings (one resource per environment). If the settings were never written, the table defaults are returned (username_identifier: off, 3-64 characters, empty reserved list) with ETag: "0" and updated_at: null. The ETag response header carries the version to send as If-Match on PATCH.

verification_policy (before_sign_in by default) and unverified_account_ttl_days (7 by default) control the unverified-account cleanup; see Update the identity settings.

Request

This operation takes no path, query or body fields. The environment comes from the credential.

Response

200 OK with the settings and the ETag header.

{
  "username_identifier": "optional",
  "username_min_length": 3,
  "username_max_length": 32,
  "reserved_usernames": ["admin", "root", "support"],
  "verification_policy": "before_sign_in",
  "unverified_account_ttl_days": 7,
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Errors

HTTP	code	When
401	`unauthenticated`	The credential is missing, invalid or revoked.
403	`insufficient_permissions`	The credential lacks the required permission.
429	`rate_limited`	The rate limit was exceeded; retry after the `Retry-After` period.
503	`service_unavailable`	A dependency is temporarily unavailable; retry after the `Retry-After` period.

Example

curl https://api.eu.keenauth.com/v1/identity-settings \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"