API Authentication - Synthreo Builder

Authentication guide for the Builder API - generate access tokens using client credentials, add Bearer authorization headers, and manage API access for multi-tenant environments.

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/builder/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).

Request Parameters

Field	Type	Required	Description
`email`	string	Yes	Your Synthreo Builder login email address
`password`	string	Yes	Your Synthreo Builder login password
`userId`	integer	Yes	Your numerical builder account ID

Example Request (cURL)

curl -X POST 'https://auth.synthreo.ai/builder/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

Field	Type	Description
`token`	string	The JWT token to be used for authenticating API requests
`role`	object	Information about the user’s role and permissions
`role.id`	integer	Numeric role ID
`role.roleName`	string	Human-readable role name (e.g., “Full Power User”)
`role.disabled`	boolean	Whether this role is currently active
`userOptions`	array	User-specific options and account memberships
`userOptions[].userId`	integer	The user’s account ID within the tenant
`userOptions[].accountName`	string	Display name for the account
`userOptions[].isOwner`	boolean	Whether this user is the account owner
`userOptions[].disabled`	boolean	Whether this user account is disabled
`lastLoginAt`	string	ISO 8601 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.

Status Code	Meaning	Common Cause
`400 Bad Request`	Malformed request	Missing required fields or invalid JSON
`401 Unauthorized`	Invalid credentials	Incorrect email, password, or userId

{
  "error": "Invalid credentials"
}

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 /builder/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.

from datetime import datetime, timedelta, timezone
import requests

class SynthreoApiClient:
    AUTH_URL = "https://auth.synthreo.ai/builder/token"
    ORIGIN = "https://builder.synthreo.ai"

    def __init__(self, email, password, user_id):
        self.email = email
        self.password = password
        self.user_id = user_id
        self.token = None
        self.token_expiry = None

    def _token_expired(self):
        if not self.token or not self.token_expiry:
            return True
        return datetime.now(timezone.utc) > (self.token_expiry - timedelta(minutes=5))

    def ensure_valid_token(self):
        if self._token_expired():
            self.authenticate()

    def authenticate(self):
        resp = requests.post(
            self.AUTH_URL,
            headers={
                "Content-Type": "application/json",
                "Origin": self.ORIGIN,
            },
            json={
                "email": self.email,
                "password": self.password,
                "userId": self.user_id,
            },
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        self.token = data.get("token")
        if not self.token:
            raise ValueError("Authentication succeeded but token missing")
        self.token_expiry = datetime.now(timezone.utc) + timedelta(hours=24)

    def make_request(self, url, method="GET", headers=None, **kwargs):
        self.ensure_valid_token()
        req_headers = {"Authorization": f"Bearer {self.token}"}
        if headers:
            req_headers.update(headers)
        return requests.request(method, url, headers=req_headers, **kwargs)

Handling Token Expiration Errors

If you receive a 401 Unauthorized response during API calls, it typically means your token has expired. Re-authenticate and retry the request:

curl -X POST 'https://auth.synthreo.ai/builder/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'

Multi-Tenant Authentication

The Synthreo platform supports multiple customers (tenants) under a single identity. When authenticating against the tenant management API at https://auth.synthreo.ai/tenant/token, you can specify a customerId to scope the token to a particular tenant:

{
  "email": "example@company.com",
  "password": "your_password",
  "customerId": 123
}

If customerId is omitted, the token is generated for your default customer. The response includes a customerOptions array listing all customers your identity has access to, which is useful for building multi-tenant applications that need to switch context between different organizations.

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
Use HTTPS exclusively for all API communications to protect credentials in transit

Related pages:

Introduction to the Builder API - overview of the API and key concepts
Cognitive Diagrams API - executing AI workflows after authenticating
Best Practices - token management patterns for production integrations