Auth - User

Base URL: https://your-domain.com

Authentication endpoints for Admin/Staff/Reseller users. Login returns a Bearer token; use Refresh Token to renew it without re-sending credentials.

API token rules: read before you integrate

Lifetime: 30 days from login or refresh (server-configurable with API_USER_TOKEN_DAYS). The exact moment is in data.expires_at (server time).
Refreshing rotates the token. POST /api/v1/users/refresh-token returns a new token and the old one stops working at once. Overwrite what you stored.
A token is revoked before expires_at when:
- the user's password is changed (by the user or by an admin): every token of that user is deleted,
- Logout / Logout All Devices is called.
A token is refused (but kept) while:
- the user account is disabled (status ≠ 1) or its partner tier is switched off: every request answers 401 Unauthenticated.,
- a non-admin user no longer holds the api_access permission: every module request answers 403. Granting api_access again makes the same token work again.
An expired or revoked token cannot be refreshed: the request gets 401 Unauthenticated.. Log in again; treat 401 as "get a new token", never as a bug.
Two-factor users must send their authenticator code (or a one-time recovery_code) with the login. See Two-Factor Login.
Login is rate-limited to 5 attempts per minute per account + IP, and 30 per minute per IP. Cache the token; don't log in per request.

New to the API?

The Quickstart walks through login, token renewal and creating a subscriber with a complete client in PHP, JavaScript, Python, Go and Rust.

Authenticate a user (Admin/Staff/Reseller) and receive an access token for API access. The email field accepts either the user's email address or username.

The server checks, in this order: the rate limit (429), the fields (422), the password (401), the two-factor code when the user has two-factor on (401), and then the account: active, partner tier switched on, and api_access for every profile except Admin and Super admin (403). A token is issued only when every check passes.

Property	Value
Endpoint	User Login
Method	POST
URL	`/api/v1/users/login`
Authentication	Not Required

Legacy alias

POST /api/auth-login accepts the same body, follows the same two-factor, api_access and rate-limit rules, and returns the same response. New integrations should use /api/v1/users/login.

Request Headers:

Header	Value	Required
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Request Body:

json

{
    "email": "[email protected]",
    "password": "your-password"
}

Parameter	Type	Required	Description
`email`	string	Yes	User's email address or username
`password`	string	Yes	User's password
`code`	string	No	Current 6-digit authenticator code. Needed only when the user has two-factor on
`recovery_code`	string	No	One of the user's two-factor recovery codes, used instead of `code`. Each recovery code works once

A user who turned on two-factor authentication in the web panel must prove it on the API too. Send the password together with code (from the authenticator app) or recovery_code:

json

{
    "email": "[email protected]",
    "password": "your-password",
    "code": "482913"
}

Without code and recovery_code the answer is 401 with "two_factor_required": true and no token. Ask the user for the code and send the login again with it.
A wrong or expired code, or an unknown or already used recovery_code, answers 401 Invalid Two-Factor Code.
A recovery code is burnt on use: the same code is refused the next time.
Users without two-factor log in with email and password only; code is ignored for them.

Success Response (200 OK):

json

{
    "status": "success",
    "message": "Login Successful",
    "data": {
        "user": {
            "id": 1,
            "name": "Admin User",
            "email": "[email protected]",
            "profile_type": 1,
            "isp_id": 1,
            "branch_id": 1
        },
        "token": "12|k3jH8sDf9aLpQwErTyUiOp1234567890abcdef",
        "token_type": "Bearer",
        "expires_at": "2025-01-02 10:30:00"
    }
}

Field	Description
`data.user.id`	The user's ID. Send it as `user_id` where an endpoint asks for one
`data.user.name`, `data.user.email`	The user's name and email address
`data.token`	Bearer token. Send it in the `Authorization` header on every protected request
`data.token_type`	Always `Bearer`
`data.expires_at`	Server time (`Y-m-d H:i:s`) when the token stops working, 30 days after login by default
`data.user.profile_type`	`1` Admin, `2` Admin staff, `3` Reseller, `4` Sub-reseller, `5` Retailer, `6`/`7`/`8` staff of a reseller / sub-reseller / retailer, `100` Super admin. It decides what the user sees. Every type except `1` and `100` needs the `api_access` permission
`data.user.isp_id`, `data.user.branch_id`	The user's own ISP and branch. Pass these as `isp_id` / `branch_id` on multi-tenant endpoints; other values are refused

Error Response (401 Unauthorized):

json

{
    "status": "error",
    "message": "Invalid Username Or Email Or Password"
}

Error Response (401 Unauthorized, two-factor code missing):

json

{
    "status": "error",
    "message": "Two-Factor Code Required",
    "two_factor_required": true
}

Error Response (401 Unauthorized, two-factor code wrong):

json

{
    "status": "error",
    "message": "Invalid Two-Factor Code",
    "two_factor_required": true
}

No token is issued in either two-factor case. Check two_factor_required to tell these apart from a wrong password.

Error Response (403 Forbidden):

json

{
    "status": "error",
    "message": "You Do Not Have Permission To Access The API. Please Contact Administrator."
}

Returned when a non-admin user's role does not hold the api_access permission. The same status is returned with:

Message	When
`Your Account Is Not Active. Please Contact Administrator.`	The user is disabled (`status` ≠ 1)
`Your account type is switched off. Please contact the administrator.`	The user's partner tier is switched off

Error Response (422 Validation Error):

json

{
    "status": "error",
    "message": "Validation Failed",
    "errors": {
        "email": ["The email field is required."],
        "password": ["The password field is required."]
    }
}

Error Response (429 Too Many Requests):

json

{
    "message": "Too Many Attempts."
}

Limit	Key
5 per minute	the account (the `email` value, case-insensitive) + client IP
30 per minute	the client IP, all accounts together

So one account's failed attempts do not lock out the other staff behind the same IP. The Retry-After response header says how many seconds to wait.

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/users/login" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/users/login', [
    'headers' => [
        'Accept'        => 'application/json',
    ],
    'json' => [
        'email'    => '[email protected]',
        'password' => 'your-password',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';

const response = await fetch(`${BASE_URL}/api/v1/users/login`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'your-password',
  }),
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"

response = requests.post(
    f"{BASE_URL}/api/v1/users/login",
    headers={
        "Accept": "application/json",
    },
    json={
        "email": "[email protected]",
        "password": "your-password",
    },
)

data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"

func main() {
	endpoint := baseURL + "/api/v1/users/login"

	payload, _ := json.Marshal(map[string]any{
		"email":    "[email protected]",
		"password": "your-password",
	})
	req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;
use serde_json::json;

const BASE_URL: &str = "https://your-domain.com";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/users/login"))
        .header("Accept", "application/json")
        .json(&json!({
            "email": "[email protected]",
            "password": "your-password"
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Profile (Get Current User)

Retrieve the authenticated user's profile. Useful to verify a stored token is still valid.

Property	Value
Endpoint	Get Current User
Method	GET
URL	`/api/v1/users/profile`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Request Body: None

Success Response (200 OK):

json

{
    "status": "success",
    "data": {
        "user": {
            "id": 1,
            "name": "Admin User",
            "username": "admin",
            "email": "[email protected]",
            "phone": "01712345678",
            "profile_type": 1,
            "isp_id": 1,
            "branch_id": 1,
            "status": 1
        }
    }
}

Error Response (401 Unauthorized):

json

{
    "message": "Unauthenticated."
}

Code Examples:

bash

curl -X GET "https://your-domain.com/api/v1/users/profile" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('GET', '/api/v1/users/profile', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/users/profile`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.get(
    f"{BASE_URL}/api/v1/users/profile",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/users/profile"

	req, _ := http.NewRequest("GET", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .get(format!("{BASE_URL}/api/v1/users/profile"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Refresh Token

Exchange the current token for a new one with a fresh full lifetime (30 days by default). The old token is revoked immediately, so replace the stored token with the new one from the response.

Call this shortly before expires_at (for example when less than a day is left). If the token has already expired the request fails with 401; log in again instead.

The account is checked again before a new token is issued, so a refresh does not keep a token alive for a user who has lost access.

Property	Value
Endpoint	Refresh Token
Method	POST
URL	`/api/v1/users/refresh-token`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Request Body: None

Success Response (200 OK):

json

{
    "status": "success",
    "message": "Token Refreshed Successfully",
    "data": {
        "token": "13|Zx9cVbNm7QwErTyUiOp0987654321fedcba",
        "token_type": "Bearer",
        "expires_at": "2025-01-03 10:30:00"
    }
}

Error Response (401 Unauthorized):

json

{
    "message": "Unauthenticated."
}

Returned when the token is invalid, revoked or already expired, and while the user is disabled (status ≠ 1) or its partner tier is switched off. Log in again to get a new token (a disabled user cannot until an admin enables the account).

Error Response (403 Forbidden):

json

{
    "status": "error",
    "message": "You Do Not Have Permission To Access The API. Please Contact Administrator."
}

Returned when a non-admin user's role no longer holds the api_access permission. Nothing is rotated: the current token is kept and works again once api_access is granted back. A subscriber token sent here answers 403 Oops! Insufficient Permission.

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/users/refresh-token" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/users/refresh-token', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/users/refresh-token`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.post(
    f"{BASE_URL}/api/v1/users/refresh-token",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/users/refresh-token"

	req, _ := http.NewRequest("POST", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/users/refresh-token"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Logout

Revoke the current token. Other tokens for the same user (e.g. another device) keep working.

Property	Value
Endpoint	User Logout
Method	POST
URL	`/api/v1/users/logout`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Request Body: None

Success Response (200 OK):

json

{
    "status": "success",
    "message": "Logged Out Successfully"
}

Error Response (401 Unauthorized):

json

{
    "message": "Unauthenticated."
}

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/users/logout" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/users/logout', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/users/logout`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.post(
    f"{BASE_URL}/api/v1/users/logout",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/users/logout"

	req, _ := http.NewRequest("POST", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/users/logout"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Logout All Devices

Revoke every token issued to the current user.

Property	Value
Endpoint	User Logout All
Method	POST
URL	`/api/v1/users/logout-all`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Request Body: None

Success Response (200 OK):

json

{
    "status": "success",
    "message": "Logged Out From All Devices Successfully"
}

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/users/logout-all" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/users/logout-all', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/users/logout-all`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.post(
    f"{BASE_URL}/api/v1/users/logout-all",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/users/logout-all"

	req, _ := http.NewRequest("POST", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/users/logout-all"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Auth - User ​

Login ​

Two-Factor Login ​

Profile (Get Current User) ​

Refresh Token ​

Logout ​

Logout All Devices ​

Auth - User

Login

Two-Factor Login

Profile (Get Current User)

Refresh Token

Logout

Logout All Devices