Skip to main content

​
Authentication

The Convertly API uses JWT (JSON Web Token) Bearer tokens for authentication. You need a valid token for every API request.

​
Getting a Token

Send a POST request to the login endpoint with your brand account credentials: 
curl -X POST https://api.convertlyhq.com/v1/auth/brand/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourbrand.com",
    "password": "your_password"
  }'

​
Response

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "abc123",
      "email": "you@yourbrand.com",
      "brandId": "brand_456"
    }
  }
}

​
Using the Token

Include the token in the Authorization header of every request: 
curl https://api.convertlyhq.com/v1/affiliates \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Keep your token secret. Do not expose it in client-side code, public repositories, or browser requests. Use it only in server-side applications.

​
Token Expiry

Tokens expire after 24 hours. When a token expires, the API returns a 401 Unauthorized response: 
{
  "statusCode": 401,
  "message": "Token expired",
  "error": "Unauthorized"
}
When this happens, request a new token by calling the login endpoint again.

​
Token Refresh

For long-running integrations, you can refresh your token before it expires: 
curl -X POST https://api.convertlyhq.com/v1/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"
This returns a new token with a fresh 24-hour expiry. The old token is invalidated.

​
Scopes and Permissions

Your API token inherits the permissions of the authenticated user:
RoleAccess
Brand AdminFull read/write access to all brand data
Brand MemberRead access to all data, write access to campaigns and creators
API access is available on the Growth and Scale plans. Starter plan users will receive a 403 Forbidden response when calling the API.

​
Example: Full Authentication Flow

# 1. Get a token
TOKEN=$(curl -s -X POST https://api.convertlyhq.com/v1/auth/brand/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourbrand.com", "password": "your_password"}' \
  | jq -r '.data.accessToken')

# 2. Use the token
curl https://api.convertlyhq.com/v1/affiliates \
  -H "Authorization: Bearer $TOKEN"

# 3. Refresh before expiry
NEW_TOKEN=$(curl -s -X POST https://api.convertlyhq.com/v1/auth/refresh \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data.accessToken')