Skip to content

Authentication

Login

POST/login

Used to log in and get an api_key. Register on the Spoiler Dashboard first; the account's email must be verified before login succeeds.

Request

Auth: None ยท Content-type: application/json

Request body:

The request body is JSON.

Field name Description Type
username Username or email address of the account (exact match) str
password Account password str

Request example:

{
    "username": "user@example.com",
    "password": "secure_password"
}

Response

On success the response is not wrapped in success. The api_key is also set as the api_key cookie (max_age 1800 seconds).

{
    "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
}

Field description

Field name Description Type
api_key Session key used to authenticate further requests (?api_key= or cookie) str

Failed responses

Wrong username or password, or missing fields (HTTP 401):

{
    "failed": "Incorrect username/password! or user does not exists"
}

Email not verified (HTTP 400). A new verification email is sent on every attempt:

{
    "failed": {
        "account_verified": false,
        "verification_sent": true,
        "message": "Please verify your email. A verification link has been sent to: user@example.com"
    }
}

Two-factor authentication required (HTTP 400). A sign-in code has been sent; finish the login with POST /2fa/verify:

{
    "failed": {
        "twofa_required": true,
        "pending_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "method": "email",
        "destination": "u***@e***.com",
        "message": ""
    }
}
Field name Description Type
twofa_required Always true in this response bool
pending_token Short-lived token (about 11 minutes) for /2fa/send and /2fa/verify str
method Channel the code was sent on: email, whatsapp or sms str
destination Masked email address or phone number the code was sent to str
message Empty, or a rate-limit message (e.g. Please wait 42s before requesting another sign-in code.) when no new code was sent str

Logout

POST/logout

Used to end the current session. The api_key stops working and the api_key cookie is cleared.

Request

Auth: api_key

Request body:

None

Request example:

https://spoilerinterface.com/interface/logout?api_key=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Response

The response is not wrapped in success.

{
    "message": "Logged out"
}

To end one of your other sessions (another browser or device), use POST /sessions/logout.