Login

`POST /auth/login`

Exchange your API credentials for an access token and refresh token pair.

Request

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

package main

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

func main() {
    body, _ := json.Marshal(map[string]string{
        "username": "your_api_key",
        "password": "your_api_secret",
    })

    resp, err := http.Post(
        "{{host}}/auth/login",
        "application/json",
        bytes.NewReader(body),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result struct {
        Success bool `json:"success"`
        Data    struct {
            AccessToken      string `json:"access_token"`
            RefreshToken     string `json:"refresh_token"`
            AccessExpiresAt  string `json:"access_expires_at"`
            RefreshExpiresAt string `json:"refresh_expires_at"`
            ClientID         int    `json:"client_id"`
        } `json:"data"`
    }
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Println("Access Token:", result.Data.AccessToken)
}

Request Parameters

Key	Type	Required	Description
`username`	string	Yes	Your API key retrieved from your dashboard
`password`	string	Yes	Your API secret retrieved from your dashboard

Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "access_expires_at": "2025-01-15T13:00:00Z",
    "refresh_expires_at": "2025-01-22T12:00:00Z",
    "client_id": 42
  }
}

Response Fields

Key	Type	Description
`success`	boolean	Always `true` on success
`data.access_token`	string	JWT for authenticating API requests. Valid for 1 hour.
`data.refresh_token`	string	JWT for obtaining new token pairs. Valid for 7 days.
`data.access_expires_at`	string	ISO 8601 expiry timestamp for the access token
`data.refresh_expires_at`	string	ISO 8601 expiry timestamp for the refresh token
`data.client_id`	integer	Your client ID

Errors

400 Bad Request — Missing required fields.

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

Returned when username or password is empty or missing from the request body.

401 Unauthorized — Credentials do not match.

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

Returned when the username does not exist or the password does not match.

401 Unauthorized — Client account is disabled.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Client account is not active"
  }
}

Returned when the client exists but their account status is not Active.

403 Forbidden — Request IP is not in the client's whitelist.

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

Returned when the client has IP whitelist entries configured and the request IP does not match any allowed CIDR range.