Authentication API

The SmallPict API uses a secure, passwordless authentication flow based on One-Time Passwords (OTPs). This guide explains how to programmatically request an API key for third-party integrations or custom scripts.

All API requests must be made over HTTPS to ensure data privacy.

Base URL

All endpoints documented here are relative to:

https://api.tuxnoob.com/v1

[!IMPORTANT] The internal authentication APIs used by staff and the SmallPict web dashboard are strictly allowlisted and are not publicly documented here. Do not attempt to use /internal/ routes for plugin integrations.

1. Request OTP

To begin the authentication flow, you must request an OTP to be sent to the user's email address.

Endpoint: POST /plugin/auth/request-otp

Request Body (JSON)

{
  "email": "user@example.com",
  "site_url": "https://example.com"
}

• email (required): The email address to send the OTP to.
• site_url (optional): The URL of the site requesting access.

Response

{
  "status": "success",
  "message": "OTP sent successfully",
  "expires_in": 900
}

2. Verify OTP

Once the user receives the 6-digit code via email, submit it to the verify endpoint to receive an API Key.

Endpoint: POST /plugin/auth/verify-otp

Request Body (JSON)

{
  "email": "user@example.com",
  "otp": "123456",
  "site_url": "https://example.com"
}

• email (required): The email address used in the previous step.
• otp (required): The 6-digit OTP code.

Response

Upon successful verification, the API will provision a new API key and secret key. Store these keys securely.

{
  "status": "success",
  "api_key": "sp_live_xxxxxxxxxxxxxxxxx",
  "secret_key": "sp_sec_xxxxxxxxxxxxxxxxx",
  "message": "Authentication successful"
}

Authenticating Requests

Once you have an api_key and secret_key, you must include them in the headers of all subsequent API requests using HMAC-SHA256 signatures for security.

Pass the following headers with every request:

x-api-key: sp_live_xxxxxxxxxxxxxxxxx
x-timestamp: 1672531200
x-signature: <hmac-sha256-signature>

Signature Generation

The x-signature is a hex-encoded HMAC-SHA256 hash.

1. timestamp = current Unix timestamp
2. body_hash = SHA256 hash of the JSON payload (or e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 if empty)
3. string_to_sign = METHOD\nENDPOINT\nTIMESTAMP\nBODY_HASH
4. signature = HMAC_SHA256(secret_key, string_to_sign)

If the signature is missing or invalid, the API will return a 401 Unauthorized response.