API Authentication

Authenticate using your API credentials and obtain JWT tokens for B2B API access.

Endpoint

POST /auth/login

Authentication: None required (public endpoint)

Request Body

{
  "username": "your_api_username",
  "password": "your_api_password"
}

Parameters

Parameter	Type	Required	Description
username	string	Yes	Your API username from the dashboard
password	string	Yes	Your API password (keep secure!)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "access_expires_at": "2024-01-15T10:30:00Z",
    "refresh_expires_at": "2024-01-22T09:30:00Z",
    "client_id": 123456
  }
}

Response Fields

Field	Type	Description
access_token	string	JWT token for API authentication (valid for 1 hour)
refresh_token	string	Token to refresh access token (valid for 7 days)
access_expires_at	datetime	Access token expiration timestamp (RFC3339, UTC)
refresh_expires_at	datetime	Refresh token expiration timestamp (RFC3339, UTC)
client_id	number	Your unique client identifier

Error Responses

400 Bad Request

Invalid JSON syntax:

{
  "error": {
    "name": "SyntaxError",
    "code": "SYNTAX_ERROR",
    "message": "Invalid request body"
  }
}

Missing required fields:

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Username and password are required"
  }
}

401 Unauthorized

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials"
  }
}

This is also returned when the client account is not active.

403 Forbidden

Returned when IP whitelisting is configured and the request originates from a non-whitelisted IP:

{
  "error": {
    "name": "ForbiddenError",
    "code": "FORBIDDEN",
    "message": "IP address not authorized"
  }
}

Examples

curl -X POST {{host}}/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_api_username",
    "password": "your_api_password"
  }'

<?php
$data = [
    'username' => 'your_api_username',
    'password' => 'your_api_password'
];

$ch = curl_init('{{host}}/auth/login');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    $accessToken = $result['data']['access_token'];
    $refreshToken = $result['data']['refresh_token'];
    $expiresAt = $result['data']['access_expires_at'];
}

curl_close($ch);
?>

Next Steps

Store the access_token securely
Use the token in the Authorization header for API calls
Set up automatic token refresh before expiration
Implement logout to clear tokens

API Authentication

On this page