Authentication

The Oliver Chat API uses multiple authentication methods to suit different integration scenarios and security requirements.

Security First: All API requests must be authenticated. Choose the authentication method that best fits your use case and security requirements.

Authentication Methods

Oliver Chat API supports three primary authentication methods:

🔐 Microsoft SSO

Enterprise single sign-on integration with Microsoft Azure AD. Recommended for organizational deployments.

👤 Username/Password

Traditional authentication with email and password. Suitable for individual developer accounts.

🔑 API Keys

Long-lived tokens for server-to-server integrations and automated systems. Most common for API integrations.

Username/Password Authentication

Authenticate using email and password to receive a JWT token for subsequent API calls.

POST /api/v1/auth/login

Authenticate a user with username and password credentials.

Request Headers

Content-Type: application/json
Accept: application/json

Request Body

{
  "email": "user@advisorsasset.com",
  "password": "secure_password123"
}

Response

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FwaS5vbGl2ZXJjaGF0LmNvbSIsImF1ZCI6Im9saXZlci1jaGF0LWFwaSIsImlhdCI6MTYxNjE2MTYxNiwibmJmIjoxNjE2MTYxNjE2LCJleHAiOjE2MTYyNDgwMTYsInN1YiI6IjEyMyIsInNjb3BlcyI6WyJjaGF0LnJlYWQiLCJjaGF0LndyaXRlIl19...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "user@advisorsasset.com",
      "role": "user",
      "permissions": [
        "chat.read",
        "chat.write",
        "rag.access"
      ]
    }
  },
  "message": "Authentication successful"
}

Error Response

{
  "success": false,
  "error": {
    "code": "auth_failed",
    "message": "Invalid credentials provided",
    "details": {
      "email": "The provided credentials do not match our records."
    }
  }
}

Microsoft SSO Authentication

Integrate with Microsoft Azure AD for enterprise single sign-on capabilities.

GET /api/v1/auth/microsoft

Initiate Microsoft SSO authentication flow.

Query Parameters

Parameter	Type	Required	Description
redirect_uri	string	Yes	URL to redirect to after successful authentication
state	string	No	Optional state parameter for CSRF protection

Example Request

GET /api/v1/auth/microsoft?redirect_uri=https://yourapp.com/callback&state=random_state_string

This endpoint will redirect the user to Microsoft's authentication page. After successful authentication, Microsoft will redirect back to your specified redirect_uri with an authorization code.

GET /api/v1/auth/microsoft/callback

Handle the callback from Microsoft SSO authentication.

Query Parameters

Parameter	Type	Required	Description
code	string	Yes	Authorization code from Microsoft
state	string	No	State parameter for CSRF protection

Response

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 456,
      "name": "Jane Smith",
      "email": "jane.smith@advisorsasset.com",
      "role": "user",
      "microsoft_id": "00000000-0000-0000-0000-000000000000",
      "permissions": [
        "chat.read",
        "chat.write",
        "rag.access",
        "compliance.view"
      ]
    }
  },
  "message": "Microsoft SSO authentication successful"
}

API Key Authentication

Use API keys for server-to-server integrations and long-running applications.

Test API Key Manager

Current API Key: No API key set

POST /api/v1/auth/api-keys

Create a new API key for programmatic access.

Request Headers

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body

{
  "name": "Production Server Integration",
  "description": "API key for production server integration",
  "expires_at": "2025-12-31T23:59:59Z",
  "permissions": [
    "chat.read",
    "chat.write",
    "search.execute",
    "rag.access"
  ]
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	Descriptive name for the API key
description	string	No	Detailed description of the API key's purpose
expires_at	string	No	Expiration date (ISO 8601 format). If not provided, key never expires
permissions	array	No	Array of permissions to grant to this key

Response

{
  "success": true,
  "data": {
    "id": 789,
    "name": "Production Server Integration",
    "description": "API key for production server integration",
    "api_key": "oc_live_1234567890abcdef1234567890abcdef12345678",
    "expires_at": "2025-12-31T23:59:59Z",
    "permissions": [
      "chat.read",
      "chat.write",
      "search.execute",
      "rag.access"
    ],
    "created_at": "2025-03-18T10:30:00Z"
  },
  "message": "API key created successfully"
}

Important: The API key is only shown once during creation. Store it securely as it cannot be retrieved again.

GET /api/v1/auth/api-keys

List all API keys for the authenticated user.

Request Headers

Authorization: Bearer <your_jwt_token>

Response

{
  "success": true,
  "data": [
    {
      "id": 789,
      "name": "Production Server Integration",
      "description": "API key for production server integration",
      "api_key_preview": "oc_live_1234...5678",
      "expires_at": "2025-12-31T23:59:59Z",
      "last_used_at": "2025-03-18T15:22:00Z",
      "permissions": [
        "chat.read",
        "chat.write",
        "search.execute",
        "rag.access"
      ],
      "is_active": true,
      "created_at": "2025-03-18T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

DELETE /api/v1/auth/api-keys/{id}

Revoke an API key.

Request Headers

Authorization: Bearer <your_jwt_token>

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	API key ID to revoke

Response

{
  "success": true,
  "message": "API key revoked successfully"
}

Using Authentication Tokens

Once you have obtained an authentication token (JWT or API key), include it in the Authorization header of all API requests:

Authorization: Bearer your_token_here

JWT Token Example

GET /api/v1/chats
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Accept: application/json

API Key Example

POST /api/v1/chats/123/messages
Authorization: Bearer oc_live_1234567890abcdef1234567890abcdef12345678
Content-Type: application/json

Token Refresh

JWT tokens have a limited lifespan. Use the refresh endpoint to obtain a new token without re-authenticating.

POST /api/v1/auth/refresh

Refresh an expired JWT token.

Request Headers

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Response

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "token_type": "Bearer",
    "expires_in": 86400
  },
  "message": "Token refreshed successfully"
}

Logout

Invalidate the current authentication token.

POST /api/v1/auth/logout

Log out the current user and invalidate their token.

Request Headers

Authorization: Bearer <your_jwt_token>

Response

{
  "success": true,
  "message": "Successfully logged out"
}

Permission System

Oliver Chat API uses a granular permission system to control access to different features:

Permission	Description
chat.read	View chat conversations and messages
chat.write	Create chats and send messages
chat.delete	Delete chats and messages
rag.access	Access RAG containers and documents
rag.manage	Create and manage RAG containers
search.execute	Perform web searches
browse.execute	Browse web pages
compliance.view	View compliance flags and reports
compliance.manage	Manage compliance settings
admin.users	Manage users and permissions
admin.system	Access system administration features

Error Codes

Authentication-related error codes:

Error Code	HTTP Status	Description
auth_failed	401	Invalid credentials provided
token_expired	401	JWT token has expired
token_invalid	401	JWT token is malformed or invalid
api_key_invalid	401	API key is invalid or revoked
insufficient_permissions	403	User lacks required permissions
account_suspended	403	User account is suspended
mfa_required	428	Multi-factor authentication required

Security Best Practices

Secure Storage: Store API keys and tokens securely, never in client-side code
Token Rotation: Regularly rotate API keys and refresh JWT tokens
Principle of Least Privilege: Request only the permissions your application needs
HTTPS Only: Always use HTTPS for authentication requests
Rate Limiting: Implement rate limiting to prevent brute force attacks
Monitor Usage: Monitor API key usage for suspicious activity
Revoke Unused Keys: Regularly audit and revoke unused API keys

Compliance Note: All authentication activities are logged for compliance and security auditing. Ensure your authentication practices comply with your organization's security policies.