> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumos.com/llms.txt > Use this file to discover all available pages before exploring further. # /{connector_id}/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. ## OpenAPI ````yaml openapi/lumos-connectors.json POST /{connector_id}/info openapi: 3.0.0 info: title: Lumos Connectors description: >- # The Lumos Connector API ## 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 1. Discover available connectors 2. Learn about a specific connector 3. Configure a connector 4. (optional) Authenticate with OAuth 5. Read data from the connected tenant 6. 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: 1. **Authorization URL** - Call `get_authorization_url` to start the OAuth flow - Redirect user to the returned authorization URL 2. **Handle Callback** - Process the OAuth callback using `handle_authorization_callback` - Receive access and refresh tokens 3. **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: 1. **Direct Token Request** - Call `handle_client_credentials_request` with client credentials - Receive access token (and optionally refresh token) 2. **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: 1. Call `validate_credentials` to verify authentication 2. 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 1. **Request Format** Every request can include an optional `page` parameter: ```typescript { "page": { "token": string, // Optional: opaque token from previous response "size": number // Optional: number of items per page } } ``` 2. **Response Format** Paginated responses include a `page` field: ```typescript { "response": T[], // Array of items "page": { "token": string, // Token for the next page "size": number // Items per page } } ``` ### Using Pagination 1. **Initial Request** - Make the first request without a page token - Optionally specify a page size 2. **Subsequent Requests** - Include the `token` from the previous response - Keep the same page size for consistency 3. **End of Data** - When there's no more data, the response won't include a page token ### Example Flow ```typescript // 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 version: 0.0.0 servers: [] security: [] tags: - name: Learning about connectors - name: Open API Specification - name: Read Capabilities - name: OAuth Capabilities - name: Write Capabilities paths: /{connector_id}/info: post: tags: - Learning about connectors description: |- 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. operationId: info parameters: - name: connector_id in: path required: true schema: type: string responses: '200': description: The request has succeeded. content: application/json: schema: anyOf: - $ref: '#/components/schemas/InfoResponse' - $ref: '#/components/schemas/ErrorResponse' components: schemas: InfoResponse: type: object allOf: - type: object required: - response properties: response: $ref: '#/components/schemas/Info' raw_data: {} page: $ref: '#/components/schemas/Page' description: >- Response containing the main response payload, raw data, and pagination information. description: Response containing information about the connector ErrorResponse: type: object required: - is_error - error properties: is_error: type: boolean description: Always true for error responses. default: true error: allOf: - $ref: '#/components/schemas/Error' description: The error details. raw_data: type: object additionalProperties: {} description: Raw data associated with the error, if any. page: allOf: - $ref: '#/components/schemas/Page' description: Pagination information, if applicable. description: Error details and metadata returned when an operation fails. Info: type: object required: - app_id - version - capabilities - capability_schema - authentication_schema - credentials_schema - entitlement_types - resource_types - request_settings_schema properties: app_id: type: string description: A unique ID for this connector, that computers read. example: o365 app_vendor_domain: type: string description: >- The domain name of the company or organization that provides the third-party app. Used to identify the external vendor associated with the app. example: microsoft.com version: type: string description: |- A version string unique to a build of this connector. This may look like semantic versioning, but that may change in the future. example: 3.2.10 capabilities: type: array items: type: string description: All capabilities provided by this connector. capability_schema: type: object additionalProperties: $ref: '#/components/schemas/CapabilitySchema' description: >- A map of capability names to schemas (how to call them, what they return) oauth_scopes: type: object additionalProperties: type: string description: >- OAuth scopes for this connector per capability, eg. dict[StandardCapabilityName, string] authentication_schema: type: object additionalProperties: {} description: A JSON schema for the "auth" field on requests. credentials_schema: type: array items: type: object additionalProperties: {} description: A JSON schema for the "credentials" field on requests. logo_url: type: string description: A fully qualified URL to an image with this integration logo. user_friendly_name: type: string description: The name of the app this is integrating with. example: Microsoft Office 365 description: type: string description: 1-3 sentences describing the product/service the app provides example: >- Patch is the direct-to-consumer brand for the people who need plants most – those who live and work in the city categories: type: array items: $ref: '#/components/schemas/AppCategory' description: Categories that this app belongs to. entitlement_types: type: array items: $ref: '#/components/schemas/EntitlementType' description: A list of entitlement types supported by this connector. resource_types: type: array items: $ref: '#/components/schemas/ResourceType' description: A list of resource types supported by this connector. request_settings_schema: type: object additionalProperties: {} description: >- A JSON schema that tells clients how to send request.settings for this app. description: Provides information about the connector. Page: type: object properties: token: type: string description: |- Opaque token representing the next page of results. Include this token in subsequent requests to retrieve the next page. size: type: integer format: int32 description: |- Number of items to return per page. This should remain consistent throughout a pagination sequence. description: Pagination parameters for requests and responses. Error: type: object required: - message - error_code - app_id properties: message: type: string description: A human-readable string explaining what went wrong. example: Authentication credentials didn't work status_code: type: integer description: |- An http status code (if applicable) corresponding to the underlying app's HTTP response that triggered this error. example: 401 app_error_code: type: string description: |- An application-specific code string that can tell us more details about the underlying application code or request that triggered the error. example: my_integration.token_expired error_code: allOf: - $ref: '#/components/schemas/ErrorCode' description: >- A standard error code used by Lumos callers to respond to this error. example: unauthenticated app_id: type: string description: The ID of the app where the error occurred. example: pagerduty raised_by: type: string description: What type of exception triggered this error (if any) example: ConnectorError raised_in: type: string description: Where the exception was raised example: my_integration.integration:list_accounts description: An error that occurred during an operation. CapabilitySchema: type: object required: - argument - output properties: argument: type: object additionalProperties: {} description: JSON schema for the input arguments of the capability. output: type: object additionalProperties: {} description: JSON schema for the output of the capability. display_name: type: string description: >- An optional text to display for the integration capability, in place of the default behavior, which is to use the capability name. description: type: string description: >- An optional 1-2 sentence description of any unusual behaviors of the capability, rendered for the end user. description: The schema for a capability, including its input arguments and output. AppCategory: type: string enum: - HR_AND_LEARNING - OFFICE_AND_LEGAL - SALES_AND_SUPPORT - COMMERCE_AND_MARKETPLACES - IT_AND_SECURITY - COMMUNICATION - DESIGN_AND_CREATIVITY - OTHER - MARKETING_AND_ANALYTICS - DEVELOPERS - ACCOUNTING_AND_FINANCE - COLLABORATION - CONTENT_AND_SOCIAL_MEDIA - INTERNAL - EARLY_ACCESS description: Enum representing different categories of applications. EntitlementType: type: object required: - type_id - type_label - resource_type_id - min properties: type_id: type: string description: A unique identifier for this entitlement type. type_label: type: string description: A human-readable label for this entitlement type. resource_type_id: type: string description: >- This must be the same string as a type_id from the declared resource types min: type: integer format: uint32 description: |- How many of this type of entitlement must be assigned? If 1: all accounts must have have one. If 0: this can be removed from an active account. max: type: integer format: uint32 description: >- How many of this type of entitlement can be assigned? If 1: an account can only have one. Otherwise, accounts can have many (up to the specified max, if there is one) requirements: type: object additionalProperties: $ref: '#/components/schemas/EntitlementRequirement' description: >- The requirements for each capability. (optional) Overrides the base min/max values for the entitlement type and the specific capability. The key is the capability name. For example when create_account requires a ROLE and not a LICENSE: The requirements for LICENSE would be: #{ ... requirements: #{ StandardCapabilityName.CREATE_ACCOUNT: EntitlementRequirement(max=0) } } description: All the things we need to know about an entitlement type in this app. example: type_id: license type_label: License resource_type_id: '' min: 1 max: 1 requirements: create_account: max: 0 ResourceType: type: object required: - type_id - type_label properties: type_id: type: string description: A unique identifier for this resource type. type_label: type: string description: A human-readable label for this resource type. description: A type of resource in the connector. example: type_id: aws_account type_label: AWS Account ErrorCode: type: string enum: - not_found - internal_error - api_error - unauthorized - bad_request - permission_denied - not_implemented - unexpected_error - unsupported_operation - unknown_value - invalid_value - bad_gateway - unauthenticated - request_timeout - connection_timeout - connection_rejected - rate_limit - authentication_expired - service_error - invalid_response - client_call_error - connection_closed - creds_revoked - invalid_page_token - integration_missing_parameter description: >- Enum representing various error codes that can be returned by the connector. EntitlementRequirement: type: object properties: min: type: integer format: uint32 max: type: integer format: uint32 ````