Token Management Settings

bilgi

Reach this screen by following Administration → System Settings → Token Management Settings. These settings only affect the response body produced by the token endpoint; the default values preserve the current behavior.

Token Response Field Names

You can rename the standard field names in the JSON response body returned by the token endpoint, or drop a field from the response entirely. The default names follow the OAuth2 RFC 6749 standard.

Field	Description
access_token field name	The name of the field that carries the access token. This field is mandatory per RFC 6749 §5.1; it can be renamed but cannot be removed from the response.
token_type field name	The name of the field that carries the token type. When "Include in response" is disabled, it is omitted.
expires_in field name	The name of the field that carries the token validity duration. When "Include in response" is disabled, it is omitted.
refresh_token field name	The name of the field that carries the refresh token. When "Include in response" is disabled, it is omitted.
scope field name	The name of the scope field returned alongside the token. When "Include scope field in response" is disabled, scope is not added to the response at all.

not

These settings only affect the token response body. The scope claim embedded inside the JWT token itself is not renamed, so the receiving systems that validate the token are not affected.

expires_in Value Unit

By default the token endpoint returns the expires_in field in milliseconds (the legacy Apinizer behavior). RFC 6749 §5.1 defines expires_in as the token lifetime in seconds, so a strict OAuth2 client may misread the millisecond value (for example, interpret 60000 as ~16.6 hours instead of 60 seconds) and fail to refresh the token in time.

Option	Behavior
Emit expires_in in Seconds (Disabled by default)	When disabled, expires_in is returned in milliseconds (legacy behavior, preserved for backward compatibility). When enabled, expires_in is returned in seconds as required by RFC 6749 §5.1.

not

This option affects only the response expires_in field. The JWT exp claim (an absolute timestamp) and the X-IssuedAt / X-ExpiresAt response fields are unaffected.

uyarı

If your existing clients already compensate for the millisecond value, enabling this option will halve the lifetime they compute and may cause premature token refreshes. Leave it disabled for existing integrations; enable it for new integrations that expect RFC-compliant seconds.

Scope Validation Behavior

Scope indicates which permissions are requested with a token request and is used in the token acquisition with scope flow. The resolved scope is returned in the response body, alongside the token. This behavior works identically in both the "Manage From This Policy" and "Manage From ACL" management modes.

Which scopes are returned in the response depends on the two settings below.

Behavior on Scope Mismatch

Determines how the gateway behaves when some of the scopes requested by the client are not defined on the user or credential.

Option	Behavior
Strict — Return Error (Default)	If any requested scope is not defined, an HTTP 400 invalid_scope error is returned and no token is issued. Matches RFC 6749 §5.2.
Lenient — Issue Token with Intersection	A token is issued with only the defined scopes; invalid scopes are silently dropped.
Ignore Request — Use All Scopes	The requested scope list is ignored; the token is issued with all scopes defined on the user or credential.

Behavior When Scope Is Not Requested

Determines how the token's scope field is produced when the client requests no scope at all.

Option	Behavior
Token Without Scope (Default)	If the request does not include scope, the token is issued without scope and the scope field is omitted from the response.
Use All Scopes	If the request does not include scope, all defined scopes are used and included in the response.

Rejecting When the Principal Has No Roles

By default, when scopes are requested but the authenticated user or credential has no roles at all, the gateway fails open: it issues a token with an empty scope instead of returning an error. Enable Reject When Principal Has No Roles to make this case a hard failure that returns an HTTP 400 invalid_scope error instead, which is useful for stricter diagnostics.

Option	Behavior
Reject When Principal Has No Roles (Disabled by default)	When enabled and scopes are requested while the principal has no roles, an HTTP 400 invalid_scope error is returned. When disabled, a token with empty scope is issued (the legacy fail-open behavior).

not

This setting has no effect under the Ignore Request — Use All Scopes mismatch mode, because that mode ignores the requested scope entirely.

ipucu

For scope to be returned with a value, the relevant user or credential must have a role (scope) defined. For the role definition steps, see the Token Acquisition with Scope section. If no role is defined, scope is returned empty even in Strict mode — unless Reject When Principal Has No Roles is enabled, in which case an HTTP 400 invalid_scope error is returned.