Magic Link API Reference — Passwordless Authentication REST API

The Magic Link API lets you add passwordless authentication to any web or mobile application. You send a phone number, Mideye handles the rest — the user receives either a Mideye+ push notification or an SMS magic link and taps Accept or Reject.

How it works

Key behavior:

• Mideye Server creates a magic link page and sends the phone number to Mideye Switch
• Switch determines how to reach the user — if the user has the Mideye+ app, they receive a push notification; otherwise, they receive an SMS with a magic link
• The API call blocks until the user responds or the timeout expires
• No username or password is needed — the phone number is the identity

Prerequisites

Before making API calls, you need:

1. A Magic Link endpoint configured in the Mideye web GUI
2. An API key generated for that endpoint
3. Network access from your application to the Mideye Server HTTPS port

---

Setting up the endpoint

1. Create endpoint

   In the Mideye web GUI, navigate to External Endpoints → Magic Link Endpoints and click Add a New Magic Link Endpoint.

   Configure:

   • Endpoint Name — a unique friendly name (also used in the URL path)
   • Enable Plus Activation Links — let users activate Mideye+ through the magic link flow
   • Use Mideye+ if Activated — allow Switch to send push notifications instead of SMS for users with the Mideye+ app

2. Generate API key

   After creating the endpoint, click Edit → API Token Management → Create New API Token.

   • Friendly Name — a recognizable label for the token
   • Expiry Date — when the token expires (format: DD-MM-YYYY)

   Caution

   The API key is shown only once. Copy it immediately. If lost, create a new token.

3. Copy the endpoint URL

   On the Magic Link Endpoints page, click the Copy button to get the full URL for your endpoint.

---

API reference

Authenticate a user

Sends an authentication request to the user’s phone. The call blocks until the user responds or times out.

GET /api/sfwa/auth?msisdn={phone_number}

Or with a named endpoint:

GET /api/sfwa/auth/{endpointName}?msisdn={phone_number}

Request parameters

Parameter	Type	Required	Description
msisdn	String	Yes	URL-encoded phone number in international format, e.g. %2B46701234567
sms-text	String	No	Custom text in the SMS message
touch-timeout	Number	No	Seconds to wait for user response (15–300)
authentication-text	String	No	Text shown on the authentication page
touch-accept-text	String	No	Text shown when the user accepts
touch-reject-text	String	No	Text shown when the user rejects
button-accept-text	String	No	Custom label for the accept button
button-reject-text	String	No	Custom label for the reject button
title-text	String	No	Title text on the authentication page

Request headers

Header	Type	Required	Description
api-key	String	Yes	API key from the Magic Link endpoint

Response

The API returns a JSON object with a single code field:

{"code":"TOUCH_ACCEPTED"}

Response codes

Standard responses — the three outcomes of every authentication request:

Code	Meaning
TOUCH_ACCEPTED	User accepted the authentication
TOUCH_REJECTED	User rejected the authentication
USER_NOT_RESPONDED	Timeout — user did not respond within the allowed time

Error responses:

Code	Meaning
FAILED_DELIVERY	SMS or push could not be delivered
BAD_REQUEST	Invalid request (wrong API key, spamming, overloaded)

Assisted Login responses (only when Assisted Login is configured):

Code	Meaning
INVALID_APPROVER	Approver not found or not valid
NO_APPROVER_SELECTED	User did not select an approver

Verified responses

These are the actual JSON responses returned by Mideye Server:

{"code":"TOUCH_ACCEPTED"}
{"code":"TOUCH_REJECTED"}
{"code":"USER_NOT_RESPONDED"}

---

Example: cURL

curl -s 'https://mideye.example.com/api/sfwa/auth?msisdn=%2B46701234567' \
  -H 'api-key: c3859cad-479a-4d65-9253-459ea4a12b34'

User accepts:

{"code":"TOUCH_ACCEPTED"}

User rejects:

{"code":"TOUCH_REJECTED"}

User does not respond (timeout):

{"code":"USER_NOT_RESPONDED"}

With custom text

curl -s 'https://mideye.example.com/api/sfwa/auth?msisdn=%2B46701234567&sms-text=Login+to+MyApp&title-text=MyApp+Login&touch-timeout=60' \
  -H 'api-key: c3859cad-479a-4d65-9253-459ea4a12b34'

---

Assisted Login

The Magic Link API also supports Assisted Login — a workflow where a user requests authentication and a second person (the approver) must confirm it. This is used for help desk scenarios, shared workstations, or high-security environments.

To use Assisted Login:

1. Create an Assisted Login Profile in the Mideye web GUI
2. Assign it to the Magic Link endpoint
3. Configure which directory (LDAP, Entra ID, or local database) to search for approvers

The API call flow with Assisted Login:

1. User receives a magic link and accepts
2. User selects an approver from a list
3. Approver receives a push notification and accepts or rejects

---

Rate limiting and security

The Magic Link API includes built-in protection:

Protection	Description
Per-number rate limit	Max requests per minute and per hour per phone number
Overload protection	Max concurrent pending requests across all endpoints
API key validation	Invalid keys return BAD_REQUEST
Token expiry	API keys have configurable expiry dates

---

Next steps

Example applications

Ready-to-run code in Python, Java, C#, and Go. View on GitHub →

Quick test

Test the API with cURL or PowerShell — no code to install. View examples →

Networking requirements

Firewall rules for API access. View requirements →