EN Reference Security Models

Security, roles, rate limits and protection fields

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

These tables were generated from the Pydantic models and JSON Schema at the pinned commit. Usage guides: Authentication, authorization, protection.

“Required” means the field must be present in JSON; acceptance of null is a separate type rule. A Model() default creates that model using its documented defaults. Empty lists/objects are created separately for each instance. — means no default or no constraint for that column.

Cross-field validators apply in addition to the table: permission/public selection, URL/host safety, tenant/owner columns, cache/idempotency/transaction combinations, schema collisions and safe regex. JSON Schema validation alone does not replace forge validate. Unknown fields are rejected through extra="forbid".

SecurityConfig

Field	Type	Required	Default	Schema constraints
api_key_header	string	No	"X-API-Key"	—
bootstrap_enabled	boolean	No	false	—
bootstrap_admin_key	string | null	No	null	—
bootstrap_one_time	boolean	No	true	—
jwt_enabled	boolean	No	false	—
jwt_provider	enum ["local_hs256","jwks"]	No	"local_hs256"	—
jwt_secret	string | null	No	null	—
jwt_exp_minutes	integer	No	60	min=1
jwt_jwks_url	string | null	No	null	—
jwt_issuer	string | null	No	null	—
jwt_audience	string | list[string] | null	No	null	—
jwt_algorithms	list[string]	No	["RS256","ES256","EdDSA"]	—
jwt_subject_claim	string	No	"sub"	—
jwt_roles_claim	string	No	"roles"	—
jwt_permissions_claim	string	No	"permissions"	—
jwt_tenant_claim	string	No	"tenant_id"	—
jwt_project_claim	string	No	"project"	—
jwt_require_project_claim	boolean	No	true	—
jwt_trust_roles_claim	boolean	No	false	—
jwt_trust_permissions_claim	boolean	No	false	—
jwt_trust_tenant_claim	boolean	No	false	—
jwks_cache_ttl_seconds	integer	No	600	min=30
jwks_timeout_seconds	number	No	5.0	max=30; >=0
jwks_max_response_bytes	integer	No	1048576	min=4096; max=16777216
jwks_allow_private_networks	boolean	No	false	—
jwks_allow_insecure_http	boolean	No	false	—
allow_query_api_key	boolean	No	false	—
allow_websocket_query_api_key	boolean	No	false	—
require_https	boolean	No	false	—
allowed_ips	list[string]	No	[]	—
denied_ips	list[string]	No	[]	—
idempotency_header	string	No	"Idempotency-Key"	—
api_key_cache_ttl_seconds	number	No	2.0	min=0.0; max=60.0
api_key_cache_max_entries	integer	No	10000	min=100; max=1000000

RoleConfig

Field	Type	Required	Default	Schema constraints
permissions	list[string]	No	[]	—
inherits	list[string]	No	[]	—

RateLimitConfig

Field	Type	Required	Default	Schema constraints
enabled	boolean	No	true	—
pre_auth_enabled	boolean	No	true	—
pre_auth_requests	integer	No	1200	min=1
pre_auth_window_seconds	integer	No	60	min=1
pre_auth_burst	integer | null	No	300	min=1
requests	integer	No	120	min=1
window_seconds	integer	No	60	min=1
backend	enum ["memory","redis"]	No	"memory"	—
burst	integer | null	No	null	min=1
route_requests	integer | null	No	null	min=1
route_window_seconds	integer | null	No	null	min=1
route_burst	integer | null	No	null	min=1
memory_max_buckets	integer	No	50000	min=100
memory_idle_ttl_seconds	integer	No	600	min=10
memory_cleanup_interval_seconds	integer	No	30	min=1
fail_open	boolean	No	false	—

ProtectionConfig

Field	Type	Required	Default	Schema constraints
max_request_body_bytes	integer	No	8388608	min=1024
trusted_proxy_cidrs	list[string]	No	[]	—
max_concurrent_requests	integer	No	1000	min=1
request_timeout_seconds	number	No	30.0	>=0
trusted_hosts	list[string]	No	["*"]	—
gzip_minimum_size	integer	No	1024	min=0
reject_when_saturated	boolean	No	true	—
max_queue_wait_seconds	number	No	1.0	min=0

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/config.py
• main/schemas/project.schema.json
• main/framework/validation.py

---

English home · All English pages · Version maintenance