About Tokens 🔒

A token represents a valid session for an authenticated user associated with your application. Each token is designed with the following characteristics:

  • Passwordless: Users only need an active email account to receive a token. There is no requirement for passwords or additional credentials, simplifying the authentication process.
  • Self-contained: Each token embeds metadata —such as the user ID and application ID— which your application can use to identify users or link tokens to existing records in your user database.
  • Private: The token does not expose any user data. All embedded information is either hashed or generated randomly to ensure privacy.
  • Temporal: Tokens are created with a defined lifespan for security purposes. The expiration time is specified in the application’s configuration during its creation process.

About the Token Structure 🧩

Tokens are generated by the service and delivered to users via email. They are included as the token query parameter in a magic link, which uses the application’s redirect_url. This process ensures that the token reaches the intended recipient and that it is only valid for a limited period.

A token typically consists of two parts, separated by a delimiter. For example:

Ex.: MjAyNS0wMy0zMVQwMjoyNToyNC4xMjc3NDkrMDI6MDA.6VjTMr+lyUXtxNT7MZ17E/Mvdhtx87bJM8cTQ9El8ERokB+K9ew0AWRkI5vUjmKv1Slq5nvlfdqypege0oXgCg

The two parts are

  • App ID: This part contains the base64 representation of your app’s metadata, encoded as bytes unless your secret. It includes the name, redirect URL and session duration. This part makes the token self-contained and helps to ensure that the second part of the token is correct.
  • Session signature: This part is generated by signing the authenticated user’s email and the expiration of the token itself. The signature is created using ed25519 as the curve and the sha256 hmac of the full secret as the private key.

When a token is created for a user, the app id and app secret should be provided. These are used to compose the private key and sign the user’s email and the token’s expiration time, which is calculated using the session duration encoded in the app id.

Together, these components ensure that the token is secure, verifiable and uniquely associated with both the application and the authenticated user.

Token secret

The full secret is calculated by hashing two parts with sha256 hash: one remains private in the service (to ensure that comes from the right instance) and another defined by the app creator (to ensure that comes from your app).