BScheduler Partner Authentication Integration Gateway

Purpose of the Integration

This Partner Authentication Integration Gateway is intended to support the authentication of users from partners such as Karmak into BScheduler. The gateway provides a secure, streamlined authentication flow that allows partner systems to seamlessly integrate their users into the BScheduler platform.

Getting Started

API Key Requirements

To use this integration, partners must obtain an API key from BlueTread. Each API key is:

• Unique to the tenant/account - Ensures secure, isolated authentication
• Provided and managed by BlueTread - Contact BlueTread to receive your API key
• Required for all authentication requests - Must be included in the Authorization header

---

Partner Authentication Login Endpoint

Endpoint Details

POST /api/v1/partner-auth-login

This is the primary endpoint for partner authentication. It handles both user creation and login in a single request.

Authentication

• Authorization Header: Required - Include your tenant-specific API key provided by BlueTread

  Code
   
  Authorization: Bearer YOUR_API_KEY_HERE

Request Parameters

Required Fields

Parameter	Type	Description
userId	string	Unique identifier for the user from the integration partner system. If the userId does not exist in BScheduler, a new user will be created automatically.
userData	object	User information object (see below)
provider	string	Name of the partner requesting the authentication flow (e.g., "karmak")

userData Object

Field	Type	Required	Description
email	string	Yes	User's email address
firstName	string	Yes	User's first name
lastName	string	Yes	User's last name
contactTypeIds	array of integers	No	List of contact type identifiers (see mapping table below)

Contact Type to BScheduler Role Mapping

Contact types from the partner system are automatically mapped to BScheduler roles according to the following table.

Important Notes:

• If no contact types are provided, new users will be assigned the User role by default
• Contact types are additive - users can be assigned multiple roles. For example, if a user has contact type 16 (IT) and contact type 11 (Foreman) in the array, they will receive both the Admin and Technician roles in BScheduler

ID	Contact Type	BScheduler Role
1	Accounts Payable	User
2	Accounts Receivable	User
3	Buyer	User
4	CFO	User
5	Controller	User
6	Customer Service	User
7	Decision Maker	User
8	Dispatcher	User
9	Driver	User
10	Fleet Manager	User
11	Foreman	Technician
12	General Manager	User
13	Human Resources	User
14	Installer	User
15	Inventory Manager	User
16	IT	Admin
17	Leasing Manager	User
18	Maintenance	User
19	Marketing	User
20	Office Manager	User
21	Operations	User
22	Owner	User
23	Parts	User
24	Parts Buyer	User
25	Parts Manager	User
26	President	User
27	Procurement	User
28	Purchasing Manager	User
29	Rental Manager	User
30	Safety	User
31	Sales	User
32	Sales Manager	User
33	Scheduler	User
34	Service	User
35	Service Manager	User
36	Shop Contact	User
37	Supervisor	User
38	Technician	Technician
39	Title Clerk	User
40	Warranty Coordinator	User

Request Example

Code
 
{
  "userId": "12345",
  "provider": "karmak",
  "userData": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "contactTypeIds": [11, 38]
  }
}

Response

Upon successful authentication, the endpoint returns:

Code
 
{
  "redirectUrl": "https://bscheduler.app/auth/login?token=...",
  "expiresInSeconds": 300
}

Authentication Flow

1. User Creation or Lookup:

   • New Users: If the userId does not exist in BScheduler, a new user is created using the provided userData and contact types are automatically mapped to the appropriate BScheduler roles
   • Existing Users: If the userId exists, the existing user's information and roles remain unchanged. The user will be authenticated and signed in with their current profile and permissions

2. Login Processing:

   • The login request is processed and validated
   • A secure, one-time use authentication token is generated

3. Redirect URL:

   • A short-lived redirect URL is returned in the response
   • When followed, this URL will sign the user into BScheduler
   • The URL is valid for a limited time (typically 10 minutes) and can only be used once

Error Responses

Status Code	Description
400	Bad Request - Invalid input or missing required fields
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
500	Internal Server Error - Login processing failed
503	Service Unavailable - Backend service temporarily unavailable

---

Support

For API key requests, technical support, or questions about the integration:

• Email: [email protected]
• Purpose: API key provisioning and integration assistance