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.smallpict.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",
  "code": "123456",
  "site_url": "https://example.com"
}

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

Response

Upon successful verification, the API will provision a new API key. Store this key securely.

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

Authenticating Requests

Once you have an api_key, you must include it in the headers of all subsequent API requests (like image processing or quota checks).

Pass the API key using the Authorization header with the Bearer scheme:

Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxx

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