Synthreo User Management API Documentation

Overview

The User Management API provides comprehensive functionality for managing users, their permissions, and access to applications within the Synthreo platform. This includes adding users to companies, managing application permissions, and controlling user access across the tenant hierarchy.

Base URL

https://auth.synthreo.ai

Authentication

Description: All endpoints require authentication via JWT Bearer token.

URL: POST /auth/token

Request Body:

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

Field Descriptions:

Field	Type	Required	Description
`email`	string	Yes	Your email address
`password`	string	Yes	Your password
`customerId`	integer	No	The customer you want to generate a token for. If omitted, generates a token for your default customer.

Example Response:

{
    "token": "token here",
    "customerOptions": [
        {
            "customerId": 123,
            "displayName": "MyCompany",
            "roleName": "Admin",
            "isOwner": false
        }
    ]
}

The value in Token is your JWT token. The list of customers is the customers you have access to.

Append the following to your header in all future calls

Authorization: Bearer your_jwt_token

User Management Endpoints

Get Users in Company

Description: Retrieves all users associated with a company and their detailed permission information.

URL: GET /tenant/users/{cid?}

Requirements:

Authentication required

Parameters:

cid (optional): Company ID. If omitted, returns users for the company you generated a token for.

Example Request:

GET /tenant/users/123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

[
  {
    "id": 456,
    "firstName": "John",
    "lastName": "Doe", 
    "email": "john.doe@company.com",
    "createdAt": "2024-01-15T10:30:00Z",
    "hasPassword": true,
    "otpMethod": "Email",
    "lastAccess": "2024-08-28T09:15:00Z",
    "name": "John Doe",
    "permissions": [
      {
        "id": 1,
        "lastAccess": "2025-08-28T18:16:24.330121",
        "disabled": false,
        "createdAt": "2025-08-20T17:53:49.876681",
        "role": { ... },
        "account": { ... },
        "instanceActive": true,
        "application": { ... },
        "region": { ... }
      }
    ]
  }
]

Add User to Company

Description: Creates a new user account and adds them to the specified company with Threo access.

URL: POST /tenant/user

Requirements:

Authentication required

Request Body:

{
  "email": "newuser@company.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "name": "Jane Smith"
}

Field Descriptions:

Field	Type	Required	Description
`customerId`	integer	No	Company ID (defaults to current company if omitted)
`email`	string	Yes	Valid email address for the new user
`firstName`	string	No	First name of the user
`lastName`	string	No	Last name of the user
`name`	string	No	Full name (automatically splits into firstName/lastName if other fields are empty)

Example Request:

POST /tenant/user HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "customerId": 123,
  "email": "newuser@company.com", 
  "firstName": "Jane",
  "lastName": "Smith"
}

Response: 201 Created on success

Reinitiate User Account

Description: Resends the initial setup email to a user who hasn't completed account setup (users without passwords).

URL: POST /tenant/user/init

Requirements:

Authentication required

Request Body:

{
  "id": 456
}

Example Request:

POST /tenant/user/init HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "id": 456
}

Response: 204 No Content on success

Notes:

Only works for users who haven't set up their password yet
Returns 400 error if user has already initiated their account
For password reset of existing users, use the /auth/reset endpoint instead

Permission Management Endpoints

Get Permission Options

Description: Retrieves available options for creating permissions including applications, regions, accounts, roles, and users.

URLs: GET /permission/options?{queryparameters} - Shows list of applications with their values GET /permission/options/{type}?{queryparameters} - Shows list of regions with their values GET /permission/options/{type}/{region}?{queryparameters} - Shows list of accounts with their values GET /permission/options/{type}/{region}/{account}?{queryparameters} - Shows roles and users

Requirements:

Authentication required

Route Parameters:

Field	Type	Description
`type`	string	Application value
`region`	integer	Region value
`account`	string	account value

Query Parameters:

Field	Type	Required	Description
`cid`	integer	No	customerId
`all`	boolean	No	Include disabled accounts

Example Request:

GET /permission/options/1/1/101?cid=123 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response:

{
  "applications": [
    {
      "value": 1,
      "title": "TheoBuilder",
      "selected": true
    },
    {
      "value": 2, 
      "title": "ThreoAI",
      "selected": false
    },
    {
      "value": 3,
      "title": "Tenant management", 
      "selected": false
    }
  ],
  "regions": [
    {
      "value": 1,
      "title": "US East",
      "selected": true
    },
    {
      "value": 2,
      "title": "US West", 
      "selected": false
    }
  ],
  "accounts": [
    {
      "value": 101,
      "title": "Builder Production (id: builder_prod_123)",
      "selected": true
    }
  ],
  "roles": [
    {
      "value": 1,
      "title": "Admin",
      "selected": false
    },
    {
      "value": 2,
      "title": "User",
      "selected": false
    }
  ],
  "users": [
    {
      "value": 456,
      "title": "John Doe (john.doe@company.com)",
      "selected": false
    },
    {
      "value": 457,
      "title": "Jane Smith (jane.smith@company.com)", 
      "selected": false
    }
  ]
}

Create Account Permission

Description: Creates a new permission granting a user access to an application account with a specific role.

URL: POST /permission

Requirements:

Authentication required

Request Body:

{
  "appAccountId": 101,
  "appRoleId": 2,
  "userIdentityId": 456,
  "disabled": false
}

Field Descriptions:

Field	Type	Required	Description
`appAccountId`	integer	Yes	ID of the application account to grant access to
`appRoleId`	integer	Yes	ID of the role to assign
`userIdentityId`	integer	Yes	User ID
`disabled`	boolean	No	Whether permission is disabled (default: false)

Example Request:

POST /permission HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "appAccountId": 101,
  "appRoleId": 2,
  "userIdentityId": 456,
  "disabled": false
}

Example Response:

{
  "id": 789,
  "appAccountId": 101,
  "userIdentityId": 456,
  "appRoleId": 2,
  "lastAccess": null,
  "disabled": false,
  "createdAt": "2024-08-28T15:30:00Z",
  "createdBy": "{\"id\":123,\"email\":\"admin@company.com\"}"
}

Update Account Permission

Description: Updates an existing permission's role assignment.

URL: PUT /permission

Requirements:

Authentication required

Request Body:

{
  "id": 789,
  "appRoleId": 123
}

Example Request:

PUT /permission HTTP/1.1
Host: auth.synthreo.ai
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "id": 789,
  "appRoleId": 1
}

Response: 204 No Content on success

Toggle Account Permission

Description: Enables or disables an existing account permission.

URL: PATCH /permission/{permId}

Requirements:

Authentication required

Parameters:

permId (integer): Permission ID to toggle

Example Request:

PATCH /permission/789 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response: 204 No Content on success

Delete Account Permission

Description: Permanently deletes an account permission, removing user access to the application account.

URL: DELETE /permission/{permId}

Requirements:

Authentication required

Parameters:

permId (integer): Permission ID to delete

Example Request:

DELETE /permission/789 HTTP/1.1
Host: auth.synthreo.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response: 204 No Content on success

Permission and Access Rules

User Access Requirements:

Users can only be managed within companies you have access to (your company or its descendants)
Account permissions can only be created for application accounts belonging to accessible companies
Role assignments must belong to the same company as the application account or be system-wide roles

Permission Management Rules:

Cannot create duplicate permissions for the same user and application account
Disabled permissions preserve the relationship but prevent access
Deleting permissions permanently removes user access to the application account
Role changes require the new role to be valid for the application type

Code Examples

Add User (Python)

import requests

def add_user_to_company(customer_id, email, first_name, last_name):
    url = "https://auth.synthreo.ai/tenant/user"

    headers = {
        "Authorization": f"Bearer {access_token}"
    }

    data = {
        "customerId": customer_id,
        "email": email,
        "firstName": first_name,
        "lastName": last_name
    }

    try:
        response = requests.post(url, headers=headers, json=data)

        if not response.ok:
            error_detail = response.json().get('detail', 'Unknown error')
            raise Exception(f"Failed to add user: {error_detail}")

        return True
    except requests.exceptions.RequestException as e:
        print(f"Error adding user: {e}")
        return False

Print Company Users with Permissions (Python)

def get_company_users(customer_id=None):
    url = "https://auth.synthreo.ai/tenant/users"
    if customer_id:
        url += f"/{customer_id}"

    headers = {
        "Authorization": f"Bearer {access_token}"
    }

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    return response.json()

# Process user permissions
users = get_company_users(123):
for user in users:
    print(f"User: {user['firstName']} {user['lastName']} <{user['email']}>")
    print(f"  Has Password: {user['hasPassword']}")
    print(f"  2FA Method: {user['otpMethod']}")
    print(f"  Permissions:")
    
    for perm in user['permissions']:
        app_name = perm['application']['name']
        role_name = perm['role']['name'] 
        account_name = perm['account']['name']
        status = "Disabled" if perm['disabled'] else "Active"
        print(f"    - {app_name}: {role_name} on {account_name} ({status})")

Create Account Permission (Python)

def create_account_permission(app_account_id, role_id, user_id):
    url = "https://auth.synthreo.ai/permission"
    
    headers = {
        "Authorization": f"Bearer {access_token}"
    }
    
    data = {
        "appAccountId": app_account_id,
        "appRoleId": role_id,
        "userIdentityId": user_id,
        "disabled": False
    }
    
    response = requests.post(url, headers=headers, json=data)
    
    if not response.ok:
        error_detail = response.json().get('detail', 'Unknown error')
        if 'Permission already exists' in error_detail:
            print('User already has permission for this account')
            return False
        raise Exception(f"Failed to create permission: {error_detail}")
    
    return response.json()

Get Permission Options (Python)

def get_permission_options(app_type=None, region_id=None, account_id=None, customer_id=None):
    url = "https://auth.synthreo.ai/permission/options"
    
    # Build URL path
    if app_type:
        url += f"/{app_type}"
        if region_id:
            url += f"/{region_id}"
            if account_id:
                url += f"/{account_id}"

    headers = {
        "Authorization": f"Bearer {access_token}"
    }

    params = {}
    if customer_id:
        params['cid'] = customer_id

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    
    return response.json()

# Usage examples:
# Get all applications
options = get_permission_options(customer_id=123)

# Get regions for TheoBuilder
options = get_permission_options(1, customer_id=123)

# Get accounts for TheoBuilder in EU region
options = get_permission_options(1, 1, customer_id=123)

Reinitiate User Setup (Python)

def reinitiate_user(user_id):
    url = "https://auth.synthreo.ai/tenant/user/init"
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    data = {
        "id": user_id
    }
    
    response = requests.post(url, headers=headers, json=data)
    
    if response.status_code == 400:
        error_detail = response.json().get('detail', '')
        if 'already initiated' in error_detail:
            print("User has already set up their account.")
        return False
    elif response.status_code == 204:
        print(f"Setup email sent")
        return True
    else:
        response.raise_for_status()
        return False

Common Workflows

Complete User Onboarding Workflow

def onboard_new_user(customer_id, email, first_name, last_name, permissions):
    """
    Complete user onboarding workflow with permission assignment
    permissions: list of {'applicationId': int, 'roleId': int}
    """
    try:
        # Step 1: Add user to company
        add_user_to_company(customer_id, email, first_name, last_name)
        print(f"User {email} added to customer {customer_id}")

        # Step 2: Get user id
        user_id = next((u['id'] for u in get_company_users(customer_id) if u['email'] == email), None)
        if not user_id:
          print("Failed to find user Id")
          return False

        # Step 3: Create permissions
        for perm in permissions:
            create_account_permission(perm['applicationId'], perm['roleId'], user_id)
            print(f"Permission created: {perm['applicationName']} - {perm['roleName']}")

        return True
    except Exception as error:
        print(f"Onboarding failed: {error}")
        return False

# Usage
onboard_new_user(123, 'jsmith@company.com', 'Jane', 'Smith', [
    {'applicationId': 1, 'roleId': 4}, # Full Power User for ThreoBuilder
    {'applicationId': 2, 'roleId': 3}  # Admin for ThreoAI
])

Authorization Notes

Authentication: All endpoints require a valid JWT token in the Authorization header
Hierarchical Access Control:
- Users can only manage other users within their accessible company hierarchy
- Parent companies can manage users in subsidiary companies
- Users cannot manage permissions for companies above them in the hierarchy
Permission Validation:
- Account permissions can only be created for accounts belonging to accessible companies
- Roles must be compatible with the application type and company
- Cannot create duplicate permissions for the same user and account combination
User Identity Management:
- Email addresses are used as unique identifiers for users
- Users can be created automatically when adding permissions if they don't exist
- Name parsing automatically splits full names into first/last name components

Best Practices

User Management

Always validate email addresses before creating users
Use the permission options endpoint to populate UI dropdowns
Check user hasPassword status before attempting reinitialization
Implement proper error handling for duplicate user scenarios

Permission Management

Retrieve available options before creating permissions to ensure valid combinations
Use toggle functionality for temporary access control instead of delete/recreate
Monitor lastAccess timestamps to identify inactive users
Consider role hierarchies when assigning permissions (Admin vs User roles)

Performance Optimization

Cache permission options for form population
Batch permission operations when onboarding multiple users
Use company-specific queries to reduce data transfer

Security Considerations

Validate user access to target companies before making permission changes
Log all permission modifications for audit trails
Implement proper session management for long-running operations
Use principle of least privilege when assigning roles

Overview​

Base URL​

Authentication​

User Management Endpoints​

Get Users in Company​

Add User to Company​

Reinitiate User Account​

Permission Management Endpoints​

Get Permission Options​

Create Account Permission​

Update Account Permission​

Toggle Account Permission​

Delete Account Permission​

Permission and Access Rules​

Code Examples​

Add User (Python)​

Print Company Users with Permissions (Python)​

Create Account Permission (Python)​

Get Permission Options (Python)​

Reinitiate User Setup (Python)​

Common Workflows​

Complete User Onboarding Workflow​

Authorization Notes​

Best Practices​

User Management​

Permission Management​

Performance Optimization​

Security Considerations​

Overview

Base URL

Authentication

User Management Endpoints

Get Users in Company

Add User to Company

Reinitiate User Account

Permission Management Endpoints

Get Permission Options

Create Account Permission

Update Account Permission

Toggle Account Permission

Delete Account Permission

Permission and Access Rules

Code Examples

Add User (Python)

Print Company Users with Permissions (Python)

Create Account Permission (Python)

Get Permission Options (Python)

Reinitiate User Setup (Python)

Common Workflows

Complete User Onboarding Workflow

Authorization Notes

Best Practices

User Management

Permission Management

Performance Optimization

Security Considerations