API Reference
Start typing to search…

Connector capabilities

Getting Started

The most important capabilities allow the user to establish, and Lumos to validate, a valid connection to the underlying app.

  1. At a minimum, we require the validate_credentials capability. Depending on the authentication method(s) that the app supports, this may include some OAuth capabilities.
  2. After this, we suggest you implement read capabilities to let Lumos sync the app data into Lumos.
  3. Next,write capabilities allow Lumos to update users and their access.

Below is a list of capabilities that Lumos will call to learn about your integration without additional development work on your end.

Learning about connectors

list_connector_app_ids

List all available connector app IDs.

Returns a list of connector identifiers that can be used with this API. Each ID represents
a specific third-party connector (e.g., "pagerduty", "activedirectory", "netsuite").
This operation is typically the first step in working with the API, as the connector ID
is required for most other operations.

info

Retrieve information about a specific connector.

This operation is typically used during:

  • Initial connector setup and configuration
  • Runtime capability discovery
  • Schema validation and type checking
  • Documentation generation
  • Connector health checks

The response includes comprehensive metadata that helps understand
the connector's capabilities and requirements.

list_custom_attributes_schema

Retrieve the schema definition for all custom attributes supported by this connector.

OAuth Capabilities

get_authorization_url

Get OAuth authorization URL for a connector.

Constructs and returns the OAuth 2.0 authorization URL for the specified connector.
This URL can be used to direct users to the authorization page where they can grant
access to their account. Upon authorization completion, users will be redirected to
the specified callback URL.

handle_authorization_callback

Handle Authorization Callback

This operation processes the OAuth callback to exchange the authorization code for access and refresh tokens.

handle_client_credentials_request

Handle Client Credentials Request

This operation processes a client credentials request to obtain an access token, and optionally, a refresh token.
It is used in third-party integrations that only support the Client Credentials OAuth 2.0 flow,
sometimes called the "machine-to-machine flow" or "two-legged flow".

refresh_access_token

Refresh Access Token

Get a new access token (and possibly new refresh token) using the previous refresh token.
It is used when the current access token expires, ensuring seamless access to the API.
Lumos systems attempt to only make one of these calls at a time per app tenant.

Read Capabilities

find_entitlement_associations

Find associations between entitlements and resources in an integration system.

This operation retrieves the relationships between entitlements and their associated resources
in the third-party system. An entitlement represents a relationship that can be associated
with a user account, such as group memberships, role assignments, or workspace access.

The resource context helps identify the specific entity (like workspace, organization, etc.)
under which the entitlement exists. For global entitlements, the resource ID should be empty.

get_last_activity

Retrieve the last activity information for specified user accounts.

Activity data may include last login or last usage.

This can be useful for:

  • Identifying inactive accounts
  • Tracking last login dates and methods

list_accounts

Retrieve a list of accounts associated with the specified credentials. Response will include only active and suspended account.

Common use cases include:

  • Auditing connected accounts
  • Account discovery and synchronization

The request body allows for optional specification of custom attributes to include in the response.

list_entitlements

List all entitlements available in the connected system.

The response includes details about each entitlement including:

  • The type of entitlement (e.g. group, role, workspace)
  • The resource it applies to (empty string for global resource)
  • Integration-specific identifiers

list_resources

List all resources available in the connected system.

The response includes details about each resource including:

  • The type of resource (e.g. workspace, team, repository)
  • Integration-specific identifier
  • Human readable label

Resources help establish the contextual hierarchy for entitlements, showing which entities
can contain or be assigned different types of access controls.

validate_credentials

Validate the customer's credentials and retrieve tenant information.

This operation verifies that the credentials provided by the customer are valid and active.
It also retrieves identifying information about the customer's tenant/organization in the
integrated application.

The credentials could have been obtained through various means, such as:

  • OAuth flow
  • API keys
  • Username/password
  • Service account credentials

This endpoint should be called:

  • After obtaining new credentials to verify they work
  • Before performing other operations to ensure credentials are still valid
  • To get the tenant identifier needed for other operations

Write Capabilities

activate_account

Activate (or reactivate) an existing user account.

This operation allows you to activate or reactivate a user account that exists in the third-party system.
The behavior depends on how the specific connector implements account activation/deactivation.

Common use cases include:

  • Enabling user account access to the third-party system
  • Reactivating a previously deactivated account
  • Enabling a suspended account
  • Completing account setup after initial creation

assign_entitlement

Assign an entitlement to an account.

The assignment is subject to any constraints defined for the entitlement type, such as:

  • Minimum and maximum number of assignments allowed

Common use cases include:

  • Assigning software licenses to users
  • Granting access levels to resources
  • Allocating quota or usage limits

create_account

Create a new user account in the third-party system.

This operation creates a new user account with the specified details and required entitlements.
The account creation process may vary between integrations, but typically involves:

  • Creating the base user account with provided personal information
  • Assigning the required entitlements (permissions, licenses, etc.) that must be set during creation
  • Setting up the initial account status

Note: Only entitlements that are required for account creation should be specified here.
Optional entitlements should be assigned after creation using the assign_entitlement operation.

deactivate_account

Deactivate an existing user account in the integration system.

This operation depends on the connector-specific concept of activation/deactivation.
Different systems may handle deactivation differently - some may disable login,
others may revoke permissions while preserving the account, etc.

The account remains in the system but is made inactive according to the
connector's capabilities.

delete_account

Delete an existing user account in an integration system. This is not a reversible operation
and may result in data loss

unassign_entitlement

Unassign an Entitlement from a user account.

Depends on the constraints (e.g. min, max) of this entitlement type.