Skip to content

Two-factor authentication & magic link

Overview

When two-factor authentication (2FA) is enabled on an account, a correct username and password is not enough to get an api_key:

  1. POST /login sends a 6-digit code and returns a failed response with twofa_required: true and a pending_token (see Authentication).
  2. Optionally, POST /2fa/send resends the code.
  3. POST /2fa/verify exchanges pending_token + code for an api_key.

Codes are valid for 10 minutes. The pending_token is valid for about 11 minutes. Codes can be sent by email (default), whatsapp or sms; WhatsApp and SMS need a verified cellphone number and a message balance. If a WhatsApp or SMS send fails, the code is emailed instead.

Sending codes and sign-in links is rate limited per user: at least 60 seconds between sends and at most 5 sends per 15 minutes. A blocked send returns a failed message such as Please wait 42s before requesting another sign-in code. or Too many requests. Try again in 9m.

A magic link is a password-free alternative: POST /login/magic emails a one-time link to /board/magic/<token>, and that page calls POST /login/magic/consume to get an api_key. Links are valid for 15 minutes and work once.

Unlike /login, /2fa/verify and /login/magic/consume return the api_key inside success and do not set the api_key cookie.

2FA status

GET/2fa/status

Used to get the caller's 2FA setting and which channels are available.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/2fa/status?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

{
    "success": {
        "enabled": false,
        "method": "email",
        "methods": {
            "email": true,
            "whatsapp": false,
            "sms": false
        },
        "reasons": {
            "email": "",
            "whatsapp": "You need a verified cellphone number on your account to use WhatsApp 2FA.",
            "sms": "You need a verified cellphone number on your account to use SMS 2FA."
        },
        "destinations": {
            "email": "u***@e***.com",
            "whatsapp": "",
            "sms": ""
        }
    }
}

Field description

Field name Description Type
enabled Whether 2FA is enabled bool
method Current channel: email, whatsapp or sms str
methods Per channel, whether it can be used json
reasons Per channel, why it is unavailable (empty when available) json
destinations Per channel, the masked email address or phone number json

Enable 2FA

POST/2fa/enable

Used to enable 2FA on the caller's account, or change its channel.

Request

Auth: api_key · Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
method [Optional] email (default), whatsapp or sms. Any other value is treated as email. whatsapp and sms fail unless the cellphone number is verified. str

Request example:

https://spoilerinterface.com/interface/2fa/enable?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

{
    "method": "email"
}

Response

{
    "success": {
        "enabled": true,
        "method": "email"
    }
}

If the channel is unavailable:

{
    "failed": "Cannot enable sms 2FA. You need a verified cellphone number on your account to use SMS 2FA."
}

Disable 2FA

POST/2fa/disable

Used to disable 2FA on the caller's account. The channel is reset to email.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/2fa/disable?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

{
    "success": {
        "enabled": false,
        "method": "email"
    }
}

Resend 2FA code

POST/2fa/send

Used during a 2FA login to send a new sign-in code. Subject to the send rate limit.

Request

Auth: None (uses the pending_token from /login) · Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
pending_token The pending_token returned by /login str

Request example:

{
    "pending_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

{
    "success": {
        "method": "email",
        "destination": "u***@e***.com"
    }
}

Field description

Field name Description Type
method Channel the code was actually sent on (may be email if WhatsApp/SMS failed) str
destination Masked email address or phone number str

An expired or invalid pending_token returns:

{
    "failed": "Your sign-in session expired. Please sign in again."
}

Verify 2FA code

POST/2fa/verify

Used to finish a 2FA login: exchanges the pending_token and the received code for an api_key.

Request

Auth: None (uses the pending_token from /login) · Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
pending_token The pending_token returned by /login str
code The 6-digit code that was sent str

Request example:

{
    "pending_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "code": "123456"
}

Response

{
    "success": {
        "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
    }
}

Possible failed messages: Your sign-in session expired. Please sign in again., This code has expired. Ask for a new one., Incorrect code. Please try again.

POST/login/magic

Used to email a one-time sign-in link. The response is the same whether or not the account exists; unverified accounts get no email.

Request

Auth: None · Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
identifier Email address or username (case-insensitive) str

Request example:

{
    "identifier": "user@example.com"
}

Response

{
    "success": "If that account exists, a sign-in link has been emailed."
}

A rate-limited request returns a failed message such as Please wait 42s before requesting another sign-in link.

POST/login/magic/consume

Used to exchange the token from a magic link for an api_key. The token works once.

Request

Auth: None · Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
token The token from the link /board/magic/<token> str

Request example:

{
    "token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
}

Response

{
    "success": {
        "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
    }
}

An unknown, used or expired token returns:

{
    "failed": "This sign-in link is invalid or has expired."
}