Frequently Asked Questions About Tokens
Is it a correct security approach to define a separate JWT policy for each method?
Answer: No. By its nature, JWT is an authentication method that is best applied to all methods at once. If you want to apply authorization for individual methods, an approach based on scope definitions, as described on the Authorization page, is more appropriate.
What happens to old tokens?
Answer: A token for which the Token Never Expires option is selected never loses its validity. When this is not selected, a task running periodically in the background clears expired OAuth2 tokens. JWT tokens, since they are not stored on Apinizer, will fail the policy check if they are sent after expiry. Independently of this, the log records of token requests are never deleted.
When the rights specified by the Refresh Token Count parameter are used up, can the last acquired token continue to be used? Or, if it is refreshed again within its lifetime, does it lose its validity?
Answer: Refresh requests that exceed the count specified by the Refresh Token Count parameter fail. Such a refresh request causes no change, and the token continues to live until its lifetime expires.
Each successful refresh invalidates the OAuth2 token in use and produces a new one. A JWT token, since it cannot be changed after it is created, continues to live throughout its lifetime even if a new one is produced.
What is the type of the timestamps inside the token and how are they read?
Answer: The iat and exp fields that can be seen when the token is decoded hold the moment the token was acquired and the last moment it will be valid. Here the time is written as Epoch Time and, when converted to a readable form, is shown in UTC Date format. For example, the value "1724143156" can be read as "Tuesday, 20 August 2024 11:39:16 GMT+03:00".
If a refresh request is sent to a token whose lifetime has ended, does the token get refreshed?
Answer: Refresh requests are independent of the token's lifetime. What matters is the lifetime of the refresh token. This period begins the moment the token is acquired. The user may refresh either the moment the token is acquired or after the token has died (as long as it is before the refresh token's lifetime expires).
- Example 1 - If a token that will run for a total of 60 seconds is given 3 refresh rights with a lifetime of 60 seconds at each refresh, this token can run for a total of 60 + (60 - 60) + (2 * 60) = 180 seconds. This is because the first refresh token's lifetime starts the moment the token is acquired, and in this example it can live as long as the token.
- Example 2 - If a token that will run for a total of 60 seconds is given 3 refresh rights with a lifetime of 180 seconds at each refresh, this token can run for a total of 60 + (180 - 60) + (2 * 180) = 540 seconds. This is because the first refresh token's lifetime starts the moment the token is acquired, and in this example it can live for another 120 seconds after the token dies.
Can I send a request to another API Proxy with a token acquired for one API Proxy?
Answer: No, a token can only be used for the API Proxy it was acquired for. However, as a special case, a token acquired with an API Proxy Group key can be used for all API Proxies within the group.
I have used up the refresh token's rights; what happens if I try to refresh beyond this limit?
Answer: On the first refresh request that would exceed the refresh limit, an error message is returned stating that the usage right of this refresh request is exhausted. On subsequent requests, since this token will have been cleared, a "token not found" error message is returned. During this process, the token acquired in the last refresh can continue to be used as long as its lifetime has not ended.
A new refresh token arrives with each refresh request. Is this expected?
Answer: The generated refresh token is unique for each token. In case it is forgotten, it is shown again together with the refreshed token at each token refresh.
While the Token Never Expires option is selected, are there cases where the token cannot be used due to external factors?
Answer: Yes. In the following cases the token loses its validity:
If API Proxy Management;
- Undeploying the API Proxy for which the token was acquired.
- Changing the private key of the API Proxy for which the token was acquired.
- If the token is a JWT token, changing the Environment's JWT token validation key.
If Credential Management;
- Deleting the Credential for which the token was acquired.
- Changing the private key of the Credential for which the token was acquired.
- If the token is a JWT token, changing the Environment's JWT token validation key.
What is the difference between the "Manage From This Policy" and "Manage From ACL" options when acquiring a token?
Answer: The two options determine where token issuance is managed. When Manage From This Policy is selected, the token is acquired from the /auth/jwt or /auth/token endpoint using the related JWT/OAuth2 policy's own API Key information; the policy itself manages token issuance. When Manage From ACL is selected, token issuance is decoupled from the policy and the token is acquired from the /credential/jwt or /credential/token endpoint through credential records, so that multiple policies can share the same credential pool. For a step-by-step description of both methods, see the Token Acquisition Methods page.
What is the difference between an OAuth2 token and a JWT token?
Answer: A JWT token is a signed, self-contained token that carries all information (scope, expiry time, application information, etc.) within itself; it is not stored on Apinizer and is validated through its signature. An OAuth2 token, on the other hand, is a random string that carries no information (opaque); the related information is stored on the server side and validated by querying the server on each request. JWT is more suitable when distributed and stateless validation, or carrying information to the receiving system, is desired; OAuth2 is more suitable when central storage and revocation control are desired.
Is scope also returned together with the token I acquire?
Answer: Yes. The scope resolved during the token request is returned together with the acquired token, as the scope field in the response body. When a JWT is acquired, the scope is also embedded inside the token; in OAuth2 it appears only in the response body. This behavior is identical in both the Manage From This Policy and Manage From ACL modes. You can configure the name of the scope field in the response, or whether scope is included in the response, from the Token Management Settings page.
Can I acquire a token if some of the scopes I request are not defined?
Answer: This depends on the Behavior on Scope Mismatch setting on the Token Management Settings page. In Strict (default) mode, if any of the requested scopes is not defined, no token is issued and an HTTP 401 invalid_scope error is returned. In Lenient mode, a token is issued with only the defined scopes, and the invalid ones are silently dropped. In Ignore Request mode, the requested list is ignored and the token is issued with all defined scopes.
I requested a scope but the scope came back empty or did not appear in the response, why?
Answer: There are three common reasons. First, no role (scope) is defined for the relevant user or credential; in this case scope is returned empty even in Strict mode. Second, the request includes no scope at all, and the Behavior When Scope Is Not Requested setting is the default Token Without Scope; in this case the scope field is not added to the response. Third, the Include scope field in response option is disabled on the Token Management Settings page. For the steps to define a role for a user, see the scope section on the Token Acquisition Methods page.
Can I change the field names (e.g. access_token, scope) in the token response?
Answer: Yes. From the Token Response Field Names section on the Token Management Settings page, you can change the names of the access_token, token_type, expires_in, refresh_token, and scope fields as they are returned in the response body. Fields other than access_token can also be removed from the response entirely; access_token is mandatory per RFC 6749 §5.1, so it can only be renamed, not removed.