Authentication

Overview

External integrations use a two-token authentication system. This guide explains how to implement the Partner Token flow and create MSPC_TOKENs as bearer tokens for API access.

Authentication Flow

sequenceDiagram
    participant V as Vendor App
    participant OEM as OEM API
    participant VA as Vendor API
    participant U as MSP User

    U->>V: Initiates integration setup
    V->>OEM: Request Partner Token
    OEM->>V: Return Partner Token
    V->>V: Combine Vendor Token + Partner Token
    V->>VA: API calls with MSPC_TOKEN
    VA->>V: Return data/confirmation
    V->>U: Integration complete

Step 1: Create External Integration

Use your OEM access token to create an External Integration for a specific organization and vendor combination.

Create Integration Request

Endpoint: POST /api/oem-api/integration

Request Body:

{
  "integrationType": "external",
  "organizationId": "507f1f77bcf86cd799439011",
  "vendorId": "507f1f77bcf86cd799439012"
}

Response Body:

{
  "integration": {
    "id": "68c24cd92dfe9dd9ae53cd1b",
    "vendorId": "68c24cd92dfe9dd9ae53cd1c",
    "integrationKind": "external"
  },
  "partnerApiKey": <key>,
  "status": 201,
  "message": "Successfully created an integration for an organization"
}

Step 2: Create MSPC_TOKEN

Combine your Vendor Token with the Partner Token to create a MSPC_TOKEN for Vendor API access.

Token Combination Format

MSPC_TOKEN = VENDOR_TOKEN + ":" + PARTNER_TOKEN

Code Example (Node.js)

const authorizationToken = Buffer.from(
  `${vendorApiKey}:${partnerApiKey}`,
  'utf-8',
).toString('base64');

Step 3: Use MSPC_TOKEN for API Calls

Use the MSPC_TOKEN to authenticate with Vendor API endpoints.

Token Security Best Practices

1. Secure Storage

• Store client credentials securely (environment variables, key management systems)
• Never log or expose tokens in client-side code
• Use HTTPS for all API communications

2. Error Handling

• Implement retry logic for transient failures
• Log authentication errors for debugging
• Provide meaningful error messages to users

3. Rate Limiting

• Respect API rate limits
• Implement exponential backoff for rate limit errors
• Cache tokens to minimize authentication requests

Common Authentication Errors