About apps

An application identifies a collection of user tokens managed by an administrator. Apps contain the following information:

• Name (name): Used to identify the application in a human way, for example in the body of the magic link email sent to users during the authentication process.
• Administrator email (admin_email): The email address of the application administrator. Used to send the app secret and app identifier during app creation process.
• App Session duration (session_duration): The duration of a user session in seconds. It will define the expiration time of any token created for this app.
• Redirect URL (redirect_url): The url of your own service to redirect to the app users with the generated user token. The token will be included in the URL query param token.

Any action related to application management can be performed using the SimpleAuth.Link Web Application.

The following sections contain the documentation for the API that this web application uses, but each and every endpoint is public and can be used by anyone to build other solutions on top of it.

How to create your app

The app creation process allows the app administrator to create a new app and obtain its secret, which is used to identify your app and request tokens for your users. This process also allows administrators to define the app's information, including its name, session duration and redirect URL.

To create a new application, the administrator must send a request to api.simpleauth.link apps endpoint with the application information, including the administrator email. This address cannot be changed and the API will send the generated app secret to this address.

This secret cannot be recovered, only regenerated, so the administrator must keep it safe.

About the app secret

The app secret is generated during the app creation and regeneration secret processes. It is always sent to the app administrator's email address when it is created.

The secret is used to prove ownership of the application and only the administrator knows it, so it must not be revealed. It is used, for example, to authenticate users of the application or to manage the application itself.

The service will only store the hash of the secret to compare with the one in the request. It must be provided as an APP_SECRET HTTP header.

Manage your app

Only administrators can perform these actions. You need to get a token as administrator, using the administrator email address and the app secret to get a token. Then you must use that token to perform the following requests, but also needs to send the secret in the request headers.

Read more about how to get authenticated as administrator in the following section.

Get authenticated as administrator

To authenticate as an administrator, follow the same steps as any other user of your application, just use the administrator email address to get your token and use it to perform administrative operations. See the Auth your users section for more information on the process.

In this case, and following the format of the user token, the first two parts of the administrator token will be the same. This is because the administrator's User ID and Application ID are both generated by hashing the administrator's email address. See the tokens section to get more information.

Get your app information

As an application administrator, you can get the current application information from the api.simpleauth.link apps endpoint. It will not contain any information about the secret, nor its hash.

Update your app information

The administrator of an application can update some information about the application. Only the name, session duration and redirect URL can be updated. The changes made will take effect for the immediately following interactions.

Generate a new secret for your app

The administrator of an application can create a new application secret. This process terminates any user session by removing any user token for that application.

The process replaces the current app secret with a new one. The new application secret is sent to the administrator's email address as part of the application creation process. This process is irreversible.

Only administrators can perform this action, read more about how to get authenticated as administrator here.

Delete your app

The administrator of an application can delete your app. This process will remove every user token of that app and the app information from the service. This process is irreversible.