Introduction

The Lumos Connector API is a standardized interface for Identity and Access Management (IAM) operations across various third-party systems. It enables seamless integration between Lumos and external applications by providing a consistent set of operations called capabilities.

Each integration (referred to as a "connector") implements these capabilities to work with different third-party API providers, focusing primarily on:

User access management
License and cost tracking
User activity monitoring

Core Components

Connectors

A connector is a specialized library that acts as a bridge between Lumos and third-party applications. It handles:

Translation of Lumos requests into app-specific API calls
Conversion of app-specific responses into standardized Lumos formats
Authentication and authorization flows
Data format transformations

Capabilities

Capabilities are standardized operations that each connector can implement. They provide:

Consistent interfaces across different connectors
Predictable behavior patterns
Standardized error handling
Unified data structures

Data Model

Accounts

Accounts represent individual users or service accounts within a system.

They serve as the primary entities for access management and support lifecycle operations such as creation, activation, deactivation, and deletion.

Accounts can be associated with multiple entitlements and are typically identified by a unique account ID within the system.

Entitlements

Entitlements represent a permission or capability that can be granted to user accounts, such as a license or access level.

They define specific permissions, access rights, or memberships and are always associated with a resource, which may be global or specific.

Entitlements are categorized by entitlement_type (e.g., licenses, roles, permissions, group memberships) and have defined constraints for minimum and maximum assignments.

The naming of entitlements may vary, such as using "membership" for group associations.

Resources

Resources represent entities within an application that can be accessed or managed.

They are identified by a unique resource_type within each app and include a global resource (represented by an empty string) for top-level entities.

Resources can represent hierarchical structures, such as Workspaces containing Users and Groups, and serve as the context for entitlement assignments.

The usage of Resource IDs depends on the specific hierarchy, with an empty string for global resources and specific IDs (e.g., Workspace ID) for nested resources.

Associations

Associations define relationships from accounts to entitlements (which are resource specific).

They follow a hierarchical structure of Account -> Entitlement -> Resource, with no direct account-to-resource associations allowed.

Associations enable flexible access control models.

Note: The specific structure and use of resources and entitlements may vary depending on the integrated system's architecture and access model.

How to Use This API

Discover available connectors
Learn about a specific connector
Configure a connector
(optional) Authenticate with OAuth
Read data from the connected tenant
Write (update) data in the connected tenant

Authenticating with a Connector

Authentication Methods

Connectors support two main authentication categories:

1. Shared Secret Authentication

API Keys / Tokens
Basic Authentication (username/password)

2. OAuth-based Authentication

The API supports two OAuth flow types:

Authorization Code Flow (3-legged OAuth)

Requires a multi-step flow:

Authorization URL

Call get_authorization_url to start the OAuth flow
Redirect user to the returned authorization URL

Handle Callback

Process the OAuth callback using handle_authorization_callback
Receive access and refresh tokens

Token Management

Use refresh_access_token to maintain valid access
Store refresh tokens securely

Client Credentials Flow (2-legged OAuth)

Suitable for machine-to-machine authentication:

Direct Token Request

Call handle_client_credentials_request with client credentials
Receive access token (and optionally refresh token)

Token Management

Use refresh_access_token to maintain valid access (if refresh tokens are supported)
Store tokens securely

The flow type is configured in the connector settings and determines which capabilities are available. Both flows support customizable authentication methods (Basic Auth or request body) and different request formats (JSON, form data, or query parameters).

Validation

After obtaining credentials:

Call validate_credentials to verify authentication
Retrieve the unique tenant ID for the authenticated organization

Authentication Schema

Each connector's info.authentication_schema defines:

Required credential fields
Field formats and constraints
OAuth scopes (if applicable)

Pagination

Lumos connectors implement a standardized pagination mechanism to handle large datasets efficiently. The pagination system uses opaque tokens to maintain state across requests.

How Pagination Works

Request Format Every request can include an optional page parameter:

{
     "page": {
       "token": string,  // Optional: opaque token from previous response
       "size": number    // Optional: number of items per page
     }
   }

Response Format Paginated responses include a page field:

 {
     "response": T[],    // Array of items
     "page": {
       "token": string,  // Token for the next page
       "size": number    // Items per page
     }
   }

Using Pagination

Initial Request

Make the first request without a page token
Optionally specify a page size

Subsequent Requests

Include the token from the previous response
Keep the same page size for consistency

End of Data

When there's no more data, the response won't include a page token

Example Flow

// First request
POST /connectors/pagerduty/list_accounts
{
  "page": { "size": 100 }
}

// Response
{
  "response": [...],
  "page": {
    "token": "eyJwYWdlIjogMn0=",
    "size": 100
  }
}

// Next request
POST /connectors/pagerduty/list_accounts
{
  "page": {
    "token": "eyJwYWdlIjogMn0=",
    "size": 100
  }
}

Implementation Notes

Page tokens are opaque and should be treated as black boxes
Tokens may encode various information (page numbers, cursors, etc.)
The same page size should be used throughout a pagination sequence
Invalid or expired tokens will result in an error response