Authentication

Authentication Flow

┌─────────┐                    ┌─────────┐                    ┌─────────┐
│ Client  │                    │  Privé  │                    │Resource │
│  App    │                    │  Auth   │                    │  API    │
└────┬────┘                    └────┬────┘                    └────┬────┘
     │                              │                              │
     │ 1. POST /restful/login/      │                              │
     │ {username, password}         │                              │
     ├─────────────────────────────>│                              │
     │                              │                              │
     │ 2. {accessToken, exp}        │                              │
     │<─────────────────────────────┤                              │
     │                              │                              │
     │ 3. GET /api/endpoint         │                              │
     │ Authorization: Bearer {token}│                              │
     ├──────────────────────────────┼─────────────────────────────>│
     │                              │                              │
     │ 4. {data}                    │                              │
     │<─────────────────────────────┼──────────────────────────────┤

Obtaining an Access Token

Endpoint

POST /restful/login/

Request

{
  "username": "[email protected]",
  "password": "SecurePassword123!"
}

Response

{
  "userDetails": {
    "username": "your-username",
    "userKey": "USER-12345",
    "groups": [
      0
    ]
  },
  "roles": [
    "ANONYMOUS"
  ],
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "string",
  "executionPlatformKey": "string",
  "tenant": "tenantNameString",
  "defaultCompanyInventorySource": "MARKET",
  "status": "SUCCESS",
  "companyKey": "COMPANY-67890"
}

Using the Access Token

Include the token in the Authorization header of every API request:

GET /users/3/tenant123/priveKey/CLIENT-001 HTTP/1.1
Host: api.privemanagers.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Code Examples

Python:

import requests

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.privemanagers.com/users/3/tenant123/priveKey/CLIENT-001",
    headers=headers
)

JavaScript:

const response = await fetch(
  'https://api.privemanagers.com/users/3/tenant123/priveKey/CLIENT-001',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  }
);

cURL:

curl -X GET "https://api.privemanagers.com/users/3/tenant123/priveKey/CLIENT-001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Token Lifecycle

Expiration

Access tokens have a limited lifespan (typically 4-8 hours). The exact expiration time is provided in the exp field of the login response (Unix timestamp format).

Checking Expiration:

import time
import jwt

# Decode without verification to read expiration
decoded = jwt.decode(access_token, options={"verify_signature": False})
exp_timestamp = decoded['exp']

if time.time() >= exp_timestamp:
    print("Token expired - need to re-authenticate")

Token Renewal

Privé does not currently support refresh tokens. When your token expires, you must:

1. Call /restful/login/ again with your credentials
2. Obtain a new accessToken
3. Update your application's authentication header

Best Practice: Implement automatic token refresh 5 minutes before expiration to prevent request failures.

Security Best Practices

✅ Do's

• Store tokens securely — Use environment variables or secure vaults (never hardcode)
• Use HTTPS only — All API calls must use TLS encryption
• Implement token rotation — Refresh tokens before they expire
• Monitor for 401 responses — Automatically re-authenticate when tokens expire
• Use separate credentials — Maintain distinct credentials for UAT and Production

❌ Don'ts

• Never commit tokens to version control
• Don't share tokens across environments
• Don't log tokens in plain text
• Don't use the same password across multiple company accounts

Managing Multiple Credentials

Many integrations require access to multiple company types (e.g., Advisor + Execution Platform). You'll need to:

1. Maintain separate credentials for each company role
2. Obtain separate tokens for each credential set
3. Use the appropriate token for each API call based on which company's resources you're accessing

Example Scenario:

# Authenticate as Advisor Company
advisor_token = login("[email protected]", "password1")

# Authenticate as Execution Platform
platform_token = login("[email protected]", "password2")

# Use advisor token to get client data
client_data = get_client(advisor_token, "CLIENT-001")

# Use platform token to access product universe
products = get_products(platform_token)

Troubleshooting