Authentication

API Key Login

• Endpoint: POST /v1/auth/login

• Description: Exchanges API Key for an access token and signature token.

• Headers: Content-Type: application/json

• Body:

  Field	Type	Required	Description
  apiKey	string	Yes	Your API key

• Success Response (200):

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGc...",
    "signatureToken": "a1b2c3...",
    "expireAt": "2026-02-17T12:25:20.611Z"
  }
}

• Errors: 400, 401, 429, 500

Panel Login (Email + Password)

• Endpoint: POST /v1/auth/panel-login

• Description: Authenticates an ApiClient account for web panel access using email and password.

• Headers: Content-Type: application/json

• Body:

  Field	Type	Required	Description
  email	string	Yes	Account email
  password	string	Yes	Account password
  captcha	string	Yes	reCAPTCHA token generated by the frontend

• Success Response (200):

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGc...",
    "signatureToken": "a1b2c3...",
    "expireAt": "2026-02-17T12:25:20.611Z"
  }
}

• Errors: 400, 401, 429, 500 —>

• Errors: 400, 401, 429, 500

Forgot Password

• Endpoint: POST /v1/auth/forgot-password

• Description: Creates a recovery token and sends a localized HTML email with the reset link.

• Headers:

  • Content-Type: application/json
  • X-User-Language: pt | en | es optional, used as a language hint for the email template

• Body:

  Field	Type	Required	Description
  email	string	Yes	Account email
  captcha	string	Yes	reCAPTCHA token generated by the frontend
  lang	string	No	Preferred language override (pt, en, es)

• Success Response (200):

{
  "status": "success",
  "messages": ["If the email exists, a recovery link has been sent"]
}

• Errors: 400, 429, 500

Reset Password With Token

• Endpoint: POST /v1/auth/reset-password

• Description: Validates the recovery token, updates the password and revokes active sessions.

• Headers: Content-Type: application/json

• Body:

  Field	Type	Required	Description
  token	string	Yes	Recovery token received by email
  newPassword	string	Yes	New password with at least 8 characters

• Success Response (200):

{
  "status": "success",
  "messages": ["Password reset successfully"]
}

• Errors: 400, 429, 500

Panel Change Password

• Endpoint: POST /v1/auth/change-password

• Description: Changes ApiClient password for web panel access.

• Headers:

  • Content-Type: application/json
  • Authorization: Bearer <accessToken>

• Body:

  Field	Type	Required	Description
  currentPassword	string	Yes	Current account password
  newPassword	string	Yes	New password (min 8 chars)

• Success Response (200):

{
  "status": "success",
  "messages": ["Password updated successfully"]
}

• Errors: 400, 401, 429, 500

Access Token Lifecycle

• Tokens expire based on server configuration (typically 2 hours).
• Cache tokens securely and refresh only when expired.
• Reuse the same token across requests to reduce authentication load.

Signed Requests

Some write operations require an x-signed-request header. Create it by:

1. Sorting JSON object keys recursively.
2. JSON-serializing the normalized object.
3. HMAC-SHA512 the payload using signatureToken.
4. Send the hex digest in x-signed-request.
5. See examples by importing our Postman collection