API Authentication — Synthreo Builder

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
}
```text
### Headers

```json
{
  "Content-Type": "application/json",
  "Origin": "https://builder.synthreo.ai"
}
```text
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)

```bash
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
}'
```text
### Successful Response (200 OK)

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

```json
{
  "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"
}
```text
**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`.

```text
Authorization: Bearer YOUR_JWT_TOKEN
```text
Replace `YOUR_JWT_TOKEN` with the token you received from the authentication endpoint.

### Example with Authorization Header (cURL)

```bash
curl -X GET 'https://api.botx.cloud/your-endpoint' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Content-Type: application/json'
```text
## 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.

```python
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)

```text
### Handling Token Expiration Errors

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

```bash

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'
```text
## 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