Refreshing a JWT
DreamFactory uses JSON Web Tokens (JWT) to maintain user session on the server side in a stateless manner. One of the features of JWT is the ability to refresh the token without re-authenticating, as long as the JWT (token) is within the allowed refresh timeframe since it was created.
There are two time-to-live (TTL) values that you can configure for JWT in the .env file.
- DF_JWT_TTL
- Expiration TTL. This the time (in minutes) until the token expires. After it expires it can be refreshed until DF_JWT_REFRESH_TTL.
- DF_JWT_REFRESH_TTL
- Refresh TTL. This the time (in minutes) in which you can refresh the token. Between DF_JWT_TTL and DF_JWT_REFRESH_TTL the token can be refreshed as many times as you want without reauthenticating. After DF_JWT_REFRESH_TTL you must log in again.
For example, let's say your expiration TTL (DF_JWT_TTL) is 60 (1 hour) and your refresh TTL (DF_JWT_REFRESH_TTL) is 360 (6 hours). Your user authenticates at 09:00 and receives a JWT. This token is valid until 10:00. Between 10:00 and 15:00 it can be refreshed as many times as you like. Keep in mind that refreshing a token does not extend the window anew; it will still be subject to the original refresh expiration window because the iat claim is passed from the original token to the refreshed tokens, and this claim is used to determine the token's age. See these tutorials for more information about JWT internals:
- [JWT Introduction](https://jwt.io/introduction/)
- [The Anatomy of a JSON Web Token](https://scotch.io/tutorials/the-anatomy-of-a-json-web-token)
For these examples, assume your current session token is abc.123.efg.
Refreshing JWT as an Admin
The Admin refresh API endpoint is api/v2/system/admin/session
Request URL:
PUT https://foo.com/api/v2/system/admin/session?session_token=abc.123.efg
Note: Session token can also be supplied using X-DreamFactory-Session-Token request header.
Refreshing JWT as a User (Non-Admin)
The non-admin refresh API endpoint is api/v2/user/session
Request URL:
PUT https://foo.com/api/v2/user/session?session_token=abc.123.efg
Note: Session token can also be supplied using X-DreamFactory-Session-Token request header.
