Token Structure

Understanding Access Tokens and Refresh Tokens

Both access and refresh tokens are structured as JSON Web Tokens (JWT) and consist of three key components:

• header: contains metadata about the token, including its type and the signing algorithm used.

• payload: contains the token's claims, such as user identifiers, permissions, etc.

• signature: ensures the token's integrity and authenticity, providing a secure means to verify its validity. Any tampering with the header or payload would result in an invalid signature.

Tokens are represented as base64-encoded strings that combine three distinct sections separated by a period: header.payload.signature. Here is an example of a token with these distinct sections colored for clarity:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8AuBybw

Once the token is decoded, you will have JSON representations for the header and payload sections:

Header

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "acd744c3-aed3-4d10-886a-72b540f86e9a"
}

Payload

{
  "exp": 1679823551,
  "iat": 1679819951,
  "auth_time": 1679819951,
  "jti": "33fe7266-d966-4e48-b563-9ecae7c1e751",
  "iss": "https://login.hypersecureid.com/auth/realms/HyperID",
  "sub": "916e0e2e-46d9-4b80-8856-dd9fedb1b723",
  "typ": "Bearer",
  "azp": "client-service-app",
  "scope": "openid email keys auth",
  "sid": "995c78ad-ebfe-4aaf-97bd-1948ec19d371",
  "wallet_address": "0x…",
  "wallet_chain_id": "1",
  "email_verified": true,
  "email": "[e-mail]"
}

Last part of the token, known as the signature, is a result of a secure hash operation applied to the header and payload.

There are several helpful online JWT parsers available that allow you to inspect the contents of your token. For example, see https://jwt.io/.

In the following sections, we'll look at the specific payload fields for both the Access and Refresh tokens, and provide some insight into how they're used.