Token Refresh

In a valid session, CakeAuth primarily issued two things: Access Token and Session Token (see stateless authentication system).

Token Format

Both access token and session token signed and presented in a JSON Web Token (JWT) format. In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:

• Header - Contains metadata about the token type and the signing algorithm being used. This includes information like the algorithm (alg), token type (typ), and key identifier (kid).
• Payload - Contains the claims or assertions about the entity (typically the user) and additional data. This includes standard JWT claims like subject (sub), issued at (iat), and expiration (exp), as well as any custom claims.
• Signature - Ensures the integrity of the token by verifying that the message hasn't been tampered with. It's created by signing the encoded header and payload using the specified algorithm.

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz

By default, both access token and session token are signed with asymmetric keys using RS256 Signing ALgorithm. So the headers will typically look like this:

{
  "alg": "RS256",
  "typ": "JWT_Client",
  "kid": "key_jp73g8bu808kxpk7gwwe9grk0h1rhrj7"
}

Learn more about how CakeAuth securely sign every tokens and its cool mechanism here.

Access Token

Access token are super short-lived. By default, CakeAuth statically set the max age to be 59 seconds. Access token are the primary identifier to authenticate each request. This is the token you want to validate against whenever a request comes in to your service.

Access token can be identified by the typ flag in its headers which will by default values: JWT_Client.

Session Token

Session tokens in CakeAuth are specialized tokens designed for obtaining new access tokens. They can be identified by the typ flag in their headers with the value REF_Client. They contain additional security measures like rotation and invalidation mechanisms.

Session tokens have a longer lifespan than access tokens and are used to maintain persistent sessions. The token's lifetime can be configured through the session lifetime settings (see Session Lifetime)

Refresh Mechanism

The token refresh process in CakeAuth is designed to maintain continuous authentication while ensuring security. If you're using our prebuilt Frontend SDKs, the refresh process automatically triggers at 45 seconds (75% of the access token's lifetime) to prevent no valid token overlap case (grace period).