About Apps 📝

An application is a collection of user tokens managed by an administrator. Each app encapsulates essential information used to identify, authenticate, and manage user sessions. The app details include:

  • Name (name):
    A human-readable identifier for the application. This name is used, for example, in the body of the magic link email sent to users during the authentication process.

  • App Session Duration (session_duration):
    The duration, in seconds, of a user session. This value determines the expiration time of any token generated for the app.

  • Redirect URL (redirect_url):
    The URL of your service where users are redirected after authentication. The generated user token will be appended to this URL as a query parameter named token.

  • App Secret (secret):
    A confidential passphrase that must be kept secure. This secret is crucial for generating tokens for your application and validating the AppID.

This service does not store any information nor does it depend on any persistent storage component.

  • AppIDs are generated deterministically from the app configuration and the secret.
  • Tokens are created with embedded information that verifies both the application and the user’s identity.

Consequently, both AppIDs and Tokens are ephemeral. If they are lost, they cannot be recovered unless the original configuration (including the secret) is known.

How to Create Your App 🛠️

The process for creating a new app allows an administrator to:

  1. Register a New Application: Submit the application’s configuration—comprising its name, session duration, redirect URL, and secret—to the api.simpleauth.link apps endpoint.

  2. Obtain a Unique AppID: Upon registration, a unique AppID is generated deterministically from the provided configuration and secret. This AppID is used to identify your app and request tokens for user authentication.

  3. Secure the App Secret: The application requires a secret that serves two main purposes:

    • Validates the AppID.
    • Generates authentication tokens for users.

Important: The secret must be kept secure and is typically derived as the hash of a known preimage. If the secret is lost, the AppID must be regenerated. Note that the secret cannot be recovered, only regenerated; therefore, it is imperative that the administrator maintains its confidentiality.

About the App Secret 🔒

The app secret is composed of two parts:

  • User-Provided Part: This component is supplied by the administrator during the app creation process. It is used to prove ownership of the application and to generate the authentication tokens. Since only the administrator knows this part, it must remain confidential.

  • Backend-Defined Part: This component is determined by the backend to validate that the AppID was generated by the current backend instance. Similar to the user-provided part, it is known only to the backend and must not be disclosed.

Together, these two parts ensure that the authentication process remains secure and that the tokens generated are valid and unique to your application.