Magic Link
Passwordless authentication via email magic links.
Magic Link Authentication
Passwordless authentication that sends a one-time login link to the user's email address. The user clicks the link to authenticate without entering a password.
Request Magic Link
/api/v1/auth/magic-link/requestSend a magic link email to the specified address. The link contains a one-time token that can be exchanged for JWT tokens.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Required | The email address to send the magic link to. |
source | string | Optional | Where the magic link was requested from. One of: mobile, web. Affects the format of the generated link. |
allow_registration | boolean | Optional | If true, a new account is created when no account exists for this email. Defaults to false. |
referral_code | string | Optional | Referral code from an existing user. Only used when allow_registration is true and a new account is created. |
terms_accepted | boolean | Optional | Whether the user has accepted the terms of service. Required when allow_registration is true. |
Code Examples
curl -X POST https://api.orbai.world/api/v1/auth/magic-link/request \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"source": "web",
"allow_registration": true,
"terms_accepted": true
}'Responses
{
"success": true,
"data": {
"email": "user@example.com",
"expires_at": "2026-02-08T13:15:00Z",
"is_new_user": false,
"expires_in_minutes": 15
}
}{
"success": false,
"error": {
"code": "USER_NOT_FOUND",
"message": "No account found for this email address."
}
}{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Too many magic link requests. Please wait before trying again.",
"retry_after": 60
}
}Verify Magic Link
/api/v1/auth/magic-link/verifyExchange the magic link token for JWT access and refresh tokens. The token is single-use and expires after the time indicated in the request response.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token | string | Required | The one-time token from the magic link URL. |
device_id | string | Optional | Unique device identifier (UUID recommended). |
platform | string | Optional | Client platform. One of: ios, android, windows, macos, linux, web. |
device_name | string | Optional | Human-readable device name. |
fcm_token | string | Optional | Firebase Cloud Messaging token for push notifications. |
Code Examples
curl -X POST https://api.orbai.world/api/v1/auth/magic-link/verify \
-H "Content-Type: application/json" \
-d '{
"token": "mlk_a1b2c3d4e5f6...",
"device_id": "550e8400-e29b-41d4-a716-446655440000",
"platform": "web",
"device_name": "Chrome on MacBook"
}'Responses
{
"success": true,
"data": {
"user": {
"id": 1,
"uuid": "usr_abc123",
"username": "john_doe",
"email": "user@example.com",
"role": "USER",
"active": true
},
"tokens": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2...",
"access_token_expires_at": "2026-02-09T12:00:00Z",
"refresh_token_expires_at": "2026-03-08T12:00:00Z",
"token_type": "Bearer"
},
"subscription": {
"plan_name": "Premium",
"status": "active",
"expires_at": "2026-12-31T23:59:59Z"
},
"requires_2fa": false
}
}{
"success": false,
"error": {
"code": "INVALID_MAGIC_LINK",
"message": "This magic link is invalid or has expired. Please request a new one."
}
}Flow Overview
Request magic link
Your client calls POST /api/v1/auth/magic-link/request with the user's email. The API sends a magic link to their inbox.
User clicks the link
The user opens their email and clicks the magic link. The link redirects to your application with a token parameter in the URL.
Verify the token
Your client extracts the token from the URL and calls POST /api/v1/auth/magic-link/verify to exchange it for JWT tokens.
User is authenticated
On success, you receive the standard AuthResponse with access and refresh tokens. Store them securely and proceed with the authenticated session.
Token Expiration
Magic link tokens expire after 15 minutes and can only be used once. If the token has expired, the user must request a new magic link.
Mobile Deep Links
When source is set to mobile, the magic link uses a deep link URL scheme that opens directly in the mobile app. For web, a standard HTTPS link is used.
Related Endpoints
- Login -- Email/password authentication
- Register -- Create account with password
- OAuth Login -- Social provider authentication