Getting Started

Authentication Guide

Copy page

The Partners Portal API uses a three-level identification system to ensure secure access to resources. This guide explains the authentication model, login flow, session management, and how to make authenticated requests.

Three-Level Identification System

Every API request requires three levels of identification:

Level 1: Master Credentials

The combination of xClientID and xClientSecret identify the master of the calling broker.

• Header: xClientID - Part of the combination to identify the master
• Header: xClientSecret - Part of the combination to identify the master

Level 2: Broker Identity

The broker is verified to assess if it belongs to that master and has API access.

• Header: brokerID - Calling broker ID (integer)
• Validation: Must belong to the master identified by xClientID/xClientSecret
• Requirement: Must have API access enabled

Level 3: User Identity

The user is verified to ensure it belongs to the calling broker and has API access.

• Header: username - User name, usually the user's email, belonging to the calling broker (string)
• Validation: User Must belong to the broker specified in brokerID
• Requirement: Must have API access enabled
• Token Duration: Bearer token valid for 30 minutes of inactivity

Authentication Endpoint

POST /API/partnersPortal/authentication

Authenticates a partner user and returns a session token.

Request Headers:

Code
 
xClientID: YOUR_MASTER_CLIENT_ID
xClientSecret: YOUR_MASTER_SECRET
brokerID: 12345
username: [email protected]

Success Response (200 OK):

Code
 
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Returns a Bearer token as a string

Error Response (401 Unauthorized):

• Invalid master credentials (xClientID/xClientSecret combination)
• Broker does not belong to the master or lacks API access
• User does not belong to the broker or lacks API access

Token Details:

• The token lasts for 30 minutes of inactivity
• Use it in subsequent requests via the Authorization header as a Bearer token
• Each authenticated request resets the inactivity timer

Example Usage:

Code
 
POST /API/partnersPortal/authentication HTTP/1.1
Host: your-api-domain.com
xClientID: master_abc123
xClientSecret: secret_xyz789
brokerID: 12345
userID: 67890

Authentication Flows

Authentication Flow

Protected API Request Flow

Making Authenticated Requests

All protected endpoints require all three authentication levels plus the Bearer token:

Example Request:

Code
 
GET /API/partnersPortal/simulations HTTP/1.1
Host: your-api-domain.com
xClientID: master_abc123
xClientSecret: secret_xyz789
brokerID: 12345
username: 67890
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Security Best Practices

1. Store Credentials Securely - Never hardcode master credentials or broker/user IDs in source code
2. Use HTTPS - All requests must be made over HTTPS
3. Monitor Token Expiry - Token expires after 30 minutes of inactivity
4. Re-authenticate on Expiry - Call the authentication endpoint again when you receive 401
5. Protect Bearer Tokens - Store tokens securely and never expose them in URLs or logs
6. Track Inactivity - Remember that each authenticated request resets the 30-minute timer

Error Handling

401 Unauthorized

Indicates one of the three authentication levels failed:

• Invalid master credentials (xClientID/xClientSecret)
• Broker doesn't belong to master or lacks API access
• User doesn't belong to broker or lacks API access
• Bearer token is invalid or expired (30 minutes of inactivity)

Solution: Re-authenticate by calling /API/partnersPortal/authentication again

403 Forbidden

Authentication succeeded, but the user lacks permission for the resource.

Solution: Ensure the user has appropriate permissions for the requested operation

Next Steps

• API Commons - Learn about common headers and patterns
• API Reference - Explore protected endpoints