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:
POST /loginsends a 6-digit code and returns afailedresponse withtwofa_required: trueand apending_token(see Authentication).- Optionally,
POST /2fa/sendresends the code. POST /2fa/verifyexchangespending_token+codefor anapi_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¶
/2fa/statusUsed 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¶
/2fa/enableUsed 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
Response¶
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¶
/2fa/disableUsed 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¶
Resend 2FA code¶
/2fa/sendUsed 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:
Response¶
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:
Verify 2FA code¶
/2fa/verifyUsed 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:
Response¶
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.
Send magic link¶
/login/magicUsed 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:
Response¶
A rate-limited request returns a failed message such as Please wait 42s before requesting another sign-in link.
Consume magic link¶
/login/magic/consumeUsed 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:
Response¶
An unknown, used or expired token returns: