Skip to main content

Authentication

The Synthreo Builder API uses a JWT (JSON Web Token) based authentication model. To interact with the API, you must first obtain an access token by authenticating with your user credentials. This token must then be included in the Authorization header of all subsequent API requests.

Important: Access tokens expire after 24 hours and must be renewed by re-authenticating.

Obtaining an Access Token​

To get an access token, you need to send a POST request to the authentication endpoint with your Synthreo login credentials.

Endpoint​

POST https://auth.synthreo.ai/token

Request Body​

The request body must be a JSON object containing your email, password, and user ID (your builder account ID).

{
  "email": "your.email@domain.com",
  "password": "your_password",
  "userId": 123
}

Headers​

{
  "Content-Type": "application/json",
  "Origin": "https://builder.synthreo.ai"
}

Note: The Accept header is not required. The Origin header should be set to the application you're logging into (e.g., https://builder.synthreo.ai).

Example Request (cURL)​

curl -X POST 'https://auth.synthreo.ai/token' \
-H 'Content-Type: application/json' \
-H 'Origin: https://builder.synthreo.ai' \
-d '{
  "email": "your.email@domain.com",
  "password": "your_password",
  "userId": 123
}'

Successful Response (200 OK)​

A successful authentication request will return a JSON object containing the JWT token, role information, and user options.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnaXZlbl9uYW1lIjoiYXBpIiwiZmFtaWx5X25hbWUiOiJrZXkiLCJlbWFpbCI6InlvdXItYXBpLWtleUBib3R4LmNsb3VkIiwic3ViIjoiMTIzNCIsImFjdG9yIjoiNTY3OCIsInJvbGUiOiI0IiwianRpIjoiZXhhbXBsZS1qd3QtaWQiLCJleHAiOjE3MzcwMzkxMzYsImlzcyI6Imh0dHBzOi8vd3d3LmJvdHguY2xvdWQiLCJhdWQiOiJodHRwczovL3d3dy5ib3R4LmNsb3VkIn0.example-signature-here",
  "role": {
    "id": 4,
    "forUserId": null,
    "roleName": "Full Power User",
    "description": "FPU can do everything what admin can, except the membership management of other members.",
    "featuresJson": "{\"system\": {\"systemRole\": true}, \"custom\": {\"permissionKeys\": [...]}}",
    "disabled": false,
    "createdOn": "2022-03-07T00:00:00"
  },
  "userOptions": [
    {
      "userId": 1234,
      "accountName": "API User",
      "createdOn": "2025-01-15T12:00:44.1",
      "closedOn": null,
      "isOwner": false,
      "roleId": 4,
      "roleName": "Full Power User",
      "disabled": false,
      "userRoleMemberId": 173
    }
  ],
  "lastLoginAt": "2025-01-15T12:02:57.063"
}

Response Fields:

  • token: The JWT token to be used for authenticating API requests
  • role: Information about the user's role and permissions
  • userOptions: User-specific options and settings
  • lastLoginAt: Timestamp of the last successful login

Error Responses​

If the authentication fails, the API will return an error response with a corresponding HTTP status code.

  • 400 Bad Request: The request body is malformed or missing required fields
  • 401 Unauthorized: The provided credentials (email or password) are invalid

Authentication Credentials​

Your authentication credentials consist of your regular Synthreo Builder login information:

  • Email: Your regular login email for Synthreo Builder
  • Password: Your regular login password for Synthreo Builder
  • User ID: Your numerical builder account ID (required field)

The userId parameter refers to your builder account ID. If you're unsure of your user ID, contact your Synthreo representative.

Using the Access Token​

Once you have obtained an access token, you must include it in the Authorization header of all subsequent API requests. The token should be prefixed with Bearer .

Authorization: Bearer YOUR_JWT_TOKEN

Replace YOUR_JWT_TOKEN with the token you received from the authentication endpoint.

Example with Authorization Header (cURL)​

curl -X GET 'https://api.botx.cloud/your-endpoint' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/json'

Token Expiration and Management​

Access tokens have a limited lifetime and expire after 24 hours. Since there is no separate refresh endpoint, you must re-authenticate using the /token endpoint to obtain a new token after expiration.

Token Refresh Logic​

Before making an API call, check if the cached token is still valid. If it has expired or is about to expire, request a new token using the authentication endpoint.

class SynthreoApiClient {
  constructor(email, password, userId) {
    this.email = email;
    this.password = password;
    this.userId = userId;
    this.token = null;
    this.tokenExpiry = null;
  }
  
  async ensureValidToken() {
    const now = new Date();
    const bufferTime = 5 * 60 * 1000; // 5 minutes buffer
    
    if (!this.token || !this.tokenExpiry || 
        now.getTime() > (this.tokenExpiry.getTime() - bufferTime)) {
      await this.authenticate();
    }
  }
  
  async authenticate() {
    const response = await fetch('https://auth.synthreo.ai/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Origin': 'https://builder.synthreo.ai'
      },
      body: JSON.stringify({
        email: this.email,
        password: this.password,
        userId: this.userId
      })
    });
    
    const data = await response.json();
    this.token = data.token;
    this.tokenExpiry = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours
  }
  
  async makeRequest(url, options = {}) {
    await this.ensureValidToken();
    
    return fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        ...options.headers
      }
    });
  }
}

Handling Token Expiration Errors​

If you receive a 401 Unauthorized response during API calls, it typically means your token has expired:

# Example: Re-authenticate when token expires
curl -X POST 'https://auth.synthreo.ai/token' \
-H 'Content-Type: application/json' \
-H 'Origin: https://builder.synthreo.ai' \
-d '{
  "email": "your.email@domain.com",
  "password": "your_password", 
  "userId": 123
}' \
| jq -r '.token'

Security Best Practices​

  • Never expose your credentials in client-side code or version control
  • Use environment variables or a secure secret management system to store your email and password
  • Implement token refresh logic to handle token expiration gracefully
  • Do not log sensitive information, such as passwords or access tokens
  • Store tokens securely in memory or secure storage, never in plain text files