Connector Capabilities

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.

Best Practices

1. Filtering Options: Consider implementing filtering options to allow more targeted association listing based on specific criteria (e.g., by user, by entitlement, by resource). Lumos capabilities generally don’t support filters, but local / instance-specific filters can be used together with pagination.
2. Efficient Querying: Optimize database queries or API calls to retrieve association information efficiently, especially when dealing with large numbers of associations.
3. Pagination: Implement pagination to handle large numbers of associations efficiently. Associations generally tend to be a more complex entity within the integrated system, and you can make use of nested paginated calls, etc.

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

Best Practices

1. Filtering Options: This is one of the few capabilities that accept a filtering parameter (account IDs), make sure to efficiently use this input filter.

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.

Best Practices

1. Pagination Support: Implement pagination to handle large numbers of accounts efficiently.
2. Consistent Response Format: Return account data in a standardized format to ensure consistency across different integrations.
3. Scope Awareness: Be aware of the required API scopes to perform this operation based on the service.

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

Best Practices

1. Resource-Specific Entitlements: Design the capability to list entitlements for specific resources. This allows for more granular and efficient entitlement retrieval.
2. Scope Awareness: Be aware of and document any API scopes or permissions needed to list entitlements.

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.

Best Practices

1. Resource Type Support: Clearly define and document the types of resources supported by the capability.
2. Pagination: Implement pagination to handle large numbers of resources efficiently.
3. Flexible Resource Listing: Design the capability to list different types of resources based on input pagination parameter, allowing for more versatile use of the capability.
4. Efficient Querying: Optimize database queries or API calls to retrieve resource information efficiently, especially when dealing with large numbers of resources.
5. Filtering Options: Consider implementing filtering options to allow more targeted resource listing based on specific criteria. Lumos capabilities generally don’t support filters, but local / instance-specific filters can be used.

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

The Activate Account capability is designed to enable or reinstate a user account within an integrated system. This capability typically performs the following actions:

1. Validates the provided account identifier (e.g., email address, user ID, or username).
2. Checks if the account exists and is eligible for activation.
3. Updates the account status in the system to an active state.
4. May trigger additional processes such as:
   • Sending a welcome or reactivation email to the user.
   • Restoring previously assigned permissions or entitlements.
   • Updating related systems or databases to reflect the account's active status.
5. Returns a response indicating the success of the activation process and the new account status.

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

Assign a given Account to a given Entitlement. After this operation runs, there should be a direct association between Account and an Entitlement.

It is best practice to raise an error on at least these conditions:

• Account not found
• Entitlement not found or invalid
• Entitlement cannot be assigned, or there was an error assigning it to the Account

Return True if everything succeeded in the integration, otherwise return False or raise an error.

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.

The Create Account capability is designed to create a user account within an end system. This capability typically sends an email inviting the user to join the organization, or creates the user when such an action is available.

The capability can accept custom fields, using the CustomRequest and CreatableAccount models, available in the SDK. This is especially useful if you are required to extend the input parameters by the end system, for example with a password or other specific parameters.

Ensure the newly created user_id is returned in the response.

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.

This capability typically performs the following actions:

1. Validates the provided account identifier (e.g., email address, user ID, or username).
2. Verifies that the account exists and is currently active. For accounts that are not active and not inactive, consult the API documentation for the expected behaviour.
3. Updates the account status in the system to an inactive or suspended state.
4. May perform additional actions such as:
   • Revoking or suspending active sessions for the account.
   • Temporarily removing or disabling assigned permissions or entitlements.
   • Logging the deactivation event for audit purposes.
   • Triggering notifications to relevant parties (e.g., system administrators, team leads).
5. Returns a response confirming the deactivation process and the new account status.

delete_account

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

Ensure that AccountStatus.DELETED is returned in the response object.

unassign_entitlement

Unassign an Entitlement from a user account.

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

Un-assign a given Account from a given Entitlement. After this operation runs, there should not be a direct association between Account and an Entitlement.

It is best practice to raise an error on at least these conditions:

• Account not found
• Entitlement not found or invalid
• Entitlement cannot be assigned, or there was an error assigning it to the Account

Return True if everything succeeded in the integration, otherwise return False or raise an error.