About users tokens

The token identifies a valid session of an authenticated user associated with your application. Tokens have the following characteristics:

  • Passwordless: The user only needs an active email account to get a token, no passwords or anything to remember or store, just an email account.
  • Self-contained: It contains metadata information, such as the user ID or application ID, that can be used by your application to identify your users or to store a relationship between your user database and their tokens.
  • Private: Does not reveal any user data. All self-contained information is hashed or randomly generated.
  • Temporal: The tokens are created with a limited lifespan for security reasons. The expiration time is defined into the application information during its creation process and can be modified by the administrator.

About the token

The token is generated by the service and sent to the user's email included as token query parameter of a magic link created with the redirect_url of the associated application (read more here).

The token consists of three parts:

Ex.: 9c325a938b6c2cde-9c325a93-cc4320ede45f46ef
  • Application ID: Your application's identifier, generated from the first 8 bytes of the sha256 hash of the administrator's email.
  • User ID: The user's user ID, generated from the first 4 bytes of the sha256 hash of the user's email.
  • Random ID: The token identifier, a hex string of 16 random bytes. This part is unique to each token.

Authenticate your users

To authenticate your users, you will need the user's email address. It must be sent to the api.simpleauth.link auth endpoint with the application secret. See the app secret section for more information about the secrets and how to get them.

To keep the app secret private, this process must be done in a secure environment, such as the backend.

The token will be generated and sent to the requested user email in a magic link to your service. See the magic links and tokens sections to get more information.

The authentication request can be extended using custom endpoint and token duration only for the token that will be generated:


Validate users token

To validate your users tokens, they must be sent to the api.simpleauth.link validate endpoint.