Mideye Auth API Reference — Passwordless Authentication REST API

The Mideye Auth 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 Mideye Auth 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 Mideye Auth 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 →