Skip to content

Magic Link

As an alternative to RADIUS authentication, the Mideye Server offers an API that uses the user's mobile number (MSISDN) as input for second-factor authentication. Users who have activated Mideye+ will, by default, authenticate via the app; however, this can be changed in the settings. Users without Mideye+ activation authenticate using a Magic Link sent to their phone via SMS. The SMS contains a link that opens a web page where the user can accept or reject the login. Additionally, the API can be used for Assisted Login.

To create a new Magic Link endpoint, follow these steps:

  1. Navigate to External Endpoints > Magic Link Endpoints.
  2. Click the Add a New Magic Link Endpoint button to open the configuration menu.

General Settings

  • Endpoint Name: Assign a friendly and unique name to the endpoint.
  • Enable Plus Activation Links: Check this option if users should be able to activate the app through Magic Link.
  • Use Mideye+ if Activated: Check this option to allow the app to be used when the user has Mideye+ activated. Uncheck this option if Magic Links should be the only authentication method.

Assisted Login Configuration

  • Assisted Login Profile: Assign the Assisted Login Profile specific to this endpoint.
  • Use Mideye Database: Check this box if the Mideye database should be searched for approvers.
  • LDAP Profile: Assign the LDAP profile that the Mideye Server will use to search for approvers.
  • Azure Active Directory Profile: Assign the Azure Active Directory profile that the Mideye Server will use to search for approvers.

Note

The Assisted Login configuration can utilize the database, an LDAP profile, an Entra ID profile, or all three. Configure this according to your environment's compatibility.

User Messages

The following image showcases the configurable elements that influence the user experience:

Message Configuration

API Specification

HTTP Request

To obtain the hostname for the HTTP request, navigate to the Magic Link Endpoints page and click the Copy button for the external endpoint profile created for your environment.

Endpoint URL

Replace the host part with the copied URL:

GET $\{host}\$/api/sfwa/auth

For an example, check the API Call section.

Parameter

Parameter Type Required Description
msisdn String True URL encoded phone number in international format. E.g. %2B46012345678
sms-text String False Text in the SMS link.
touch-text String False Text in the Touch accept login page.
Header Type Required Description
api-key String True Key used to authorize API calls.

HTTP Response

interface SfwaAuthResponseCode {
 TOUCH_REJECTED,
 USER_NOT_RESPONDED,
 TOUCH_ACCEPTED,
 FAILED_DELIVERY
}
interface SfwaAuthResponse {
 status: SfwaAuthResponseCode;
}

API Key

To acquire the API Key, follow these steps:

  1. Navigate to Magic Link Endpoints:

    • Go to Magic Link Endpoints in the web GUI.
    • Click the Edit button for the endpoint you intend to use.

  2. Access API Token Management:

    • Click on the API Token Management tab.
    • In this menu, select either Create New API Token... or Import Existing API Token.... In this guide, we will create a new token.

API Token Creation

Note

The API Token Management tab is only visible after a Magic Link endpoint has been created. Ensure you have configured an endpoint before attempting to access this tab.

  1. Create a New API Token:

    • Friendly Name: Enter a recognizable name for the API token.
    • Expiry Date: Set the expiration date by either typing it into the field in the format DD-MM-YYYY or by selecting a date using the calendar icon.

API Token Configuration

Note

The expiry date can be set by typing directly into the date field in the DD-MM-YYYY format or by clicking the calendar icon at the end of the field.

  1. Finalize Token Creation:

    • Click the Create button.
    • A confirmation screen will appear showing the newly created API key.

API Token Created

Important: The API Key is displayed only once. Ensure you copy the API Key before closing the window, as it cannot be retrieved later. If lost, you will need to create a new token.

Making an API Call

Below is a sample API call. Note that the API Key is partially masked for security purposes.

curl --location --request GET 'https://localhost/api/sfwa/auth?msisdn=%2B46701234567' \
--header 'api-key: c3859cad-479a-4d65-9253-459ea4******'