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 of a user session, expressed as a Go duration string (e.g. "30m", "1h", "2h30m"). 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 and the user email will be appended to this URL as query parameters named token and user.
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.

About the App ID

The App ID is a self-contained representation of the app configuration. It is generated by joining the app attributes (name, redirect URL, session duration and a truncated hash of the secret) with a separator and base64url-encoding the result. Because the App ID embeds a hash of the secret, it can only be produced by an instance that knows both the app configuration and the backend secret.

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.

Both parts are hashed with SHA-256 and concatenated to compose the full secret used to sign tokens. Together, these two parts ensure that the authentication process remains secure and that the tokens generated are valid and unique to your application.

Create Your App via the API

POST /apps
Content-Type: application/json

{
  "name": "MySuperMegaApp",
  "session_duration": "30m",
  "redirect_url": "https://example.com/callback",
  "secret": "mysupersecret"
}

Response:

{
  "id": "<your-app-id>"
}

Store the returned id (the App ID) and the secret you provided — you will need both to request and verify tokens.

Important: The secret must be kept secure. 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.

Go client example

import (
	"log"
	"time"

	"github.com/simpleauthlink/authapi/api/client"
)

func main() {
	// create the client (it performs a health check on startup)
	cli, err := client.New(&client.Config{
		APIEndpoint: "https://api.simpleauth.link",
	})
	if err != nil {
		log.Fatal(err)
	}

	// create a new App ID for the app configuration
	appID, err := cli.NewAppID("MySuperMegaApp", "https://example.com/callback", "mysupersecret", 30*time.Minute)
	if err != nil {
		log.Fatal(err)
	}

	// configure the client to use the created App ID and secret
	cli.SetupAppID(appID, "mysupersecret")
}

On this page

Apps

About the App ID

About the App Secret

Create Your App via the API

Go client example