> ## 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}/list_updated_accounts > Retrieve accounts that have been updated since a specified point in time. This operation enables efficient account synchronization by allowing clients to fetch only accounts that have been modified since their last sync. This is particularly useful for maintaining up-to-date account information across large user bases without having to fetch all accounts on every request. ## Use Cases - **Account Synchronization**: Keep local account databases in sync with the remote system's current state - **Audit Trails**: Track account changes for compliance and security purposes - **Real-time Updates**: Monitor account modifications for immediate action - **Data Migration**: Identify accounts that need to be updated during system migrations or upgrades ## Delta Query Support This operation supports delta queries for incremental synchronization: - **Initial Request**: Provide a `since` to get all accounts updated since that time - **Subsequent Requests**: Use the `cursor` from the previous response for efficient incremental updates - **Cursor Management**: Each response includes a new `cursor` for the next request ## Account Update Detection Different connectors may define "updates" differently based on their capabilities: - Profile information changes (name, email, department, etc.) - Permission or role modifications - Account status changes (active/inactive, suspended, etc.) - Custom attribute modifications - Group membership changes ## Rate Limiting Considerations - Implement exponential backoff for repeated requests - Consider batching requests for large account populations - Monitor API rate limits specific to each connector ## OpenAPI ````yaml openapi/lumos-connectors.json POST /{connector_id}/list_updated_accounts 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}/list_updated_accounts: post: tags: - Read Capabilities description: >- Retrieve accounts that have been updated since a specified point in time. This operation enables efficient account synchronization by allowing clients to fetch only accounts that have been modified since their last sync. This is particularly useful for maintaining up-to-date account information across large user bases without having to fetch all accounts on every request. ## Use Cases - **Account Synchronization**: Keep local account databases in sync with the remote system's current state - **Audit Trails**: Track account changes for compliance and security purposes - **Real-time Updates**: Monitor account modifications for immediate action - **Data Migration**: Identify accounts that need to be updated during system migrations or upgrades ## Delta Query Support This operation supports delta queries for incremental synchronization: - **Initial Request**: Provide a `since` to get all accounts updated since that time - **Subsequent Requests**: Use the `cursor` from the previous response for efficient incremental updates - **Cursor Management**: Each response includes a new `cursor` for the next request ## Account Update Detection Different connectors may define "updates" differently based on their capabilities: - Profile information changes (name, email, department, etc.) - Permission or role modifications - Account status changes (active/inactive, suspended, etc.) - Custom attribute modifications - Group membership changes ## Rate Limiting Considerations - Implement exponential backoff for repeated requests - Consider batching requests for large account populations - Monitor API rate limits specific to each connector operationId: list_updated_accounts parameters: - name: connector_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: auth: allOf: - $ref: '#/components/schemas/AuthCredential' description: The authentication credentials for the request. credentials: type: array items: $ref: '#/components/schemas/AuthCredential' allOf: - type: object required: - request properties: request: allOf: - $ref: '#/components/schemas/ListUpdatedAccounts' description: The main request payload. include_raw_data: type: boolean description: Whether to include raw data in the response. page: allOf: - $ref: '#/components/schemas/Page' description: Pagination information for the request. settings: type: object additionalProperties: {} description: >- Connector-specific settings for the request. These are settings that are shared across all capabilities. Usually contain additional required configuration options not specified by the capability schema. description: Generic request model. description: Authenticated request. responses: '200': description: The request has succeeded. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ListUpdatedAccountsResponse' - $ref: '#/components/schemas/ErrorResponse' components: schemas: AuthCredential: type: object properties: id: type: string description: The ID of the authentication schema. example: some_unique_id oauth: allOf: - $ref: '#/components/schemas/OAuthCredential' description: OAuth credentials, if using OAuth. oauth_client_credentials: allOf: - $ref: '#/components/schemas/OAuthClientCredential' description: OAuth client credentials, if using OAuth Client Credentials flow. oauth1: allOf: - $ref: '#/components/schemas/OAuth1Credential' description: OAuth 1.0a credentials, if using OAuth 1.0a. basic: allOf: - $ref: '#/components/schemas/BasicCredential' description: Basic auth credentials, if using basic auth. token: allOf: - $ref: '#/components/schemas/TokenCredential' description: Token credentials, if using token-based auth. jwt: allOf: - $ref: '#/components/schemas/JWTCredential' description: JWT credentials, if using JWT. service_account: allOf: - $ref: '#/components/schemas/ServiceAccountCredential' description: Service account credentials, if using service account. key_pair: allOf: - $ref: '#/components/schemas/KeyPairCredential' description: Key-pair credentials, if using key-pair auth. x-semantic: key-pair description: Authentication credentials, which can be one of several types. ListUpdatedAccounts: type: object properties: since: type: string format: date-time description: >- Only include accounts updated since this specific date and time. This parameter defines the cutoff point for account updates. Only accounts that have been modified since this timestamp will be included in the response. ## Format Requirements Must be a valid ISO 8601 datetime string with timezone information: - **UTC**: "2024-01-15T10:30:00Z" - **With Offset**: "2024-01-15T10:30:00+05:00" - **With Timezone**: "2024-01-15T10:30:00-08:00" ## Connector Limitations Each connector may have different limitations on how far back in time they can reliably track updates: - Some connectors may limit to 30 days - Others may support up to 1 year - Enterprise connectors might support longer periods ## Usage Guidelines - Use for initial synchronization or when resuming after a long gap - Consider the connector's data retention policies when setting this value - For ongoing syncs, prefer using `cursor` instead cursor: type: string description: >- Cursor token for delta synchronization. This token represents a point in time and should be included in subsequent requests to receive only the changes that occurred since that point. - **First request**: Omit this parameter to get all available data - **Subsequent requests**: Include the `cursor` from the previous response The cursor is typically a base64-encoded string containing timestamp and other metadata needed for the delta synchronization. custom_attributes: type: array items: type: string description: >- Optional array of custom attribute names to include in account data. This parameter allows you to specify which additional account attributes should be included in the response beyond the standard account information. ## Attribute Availability Available attributes vary by connector and may include: - **User Profile**: department, title, manager, location - **Organizational**: cost_center, employee_id, hire_date - **Custom Fields**: custom_1, custom_2, custom_role - **System-Specific**: salesforce_user_type, okta_group_membership ## Performance Considerations - Requesting many custom attributes may increase response time - Some attributes may require additional API calls by the connector - Unsupported attributes are typically ignored rather than causing errors ## Best Practices - Only request attributes you actually need - Test with small attribute lists first - Consider the connector's rate limits when requesting many attributes - Cache attribute availability information when possible description: >- Request parameters for listing updated accounts with delta query support. This model extends the Delta model to provide both traditional date-based filtering and efficient cursor-based incremental synchronization. ## Parameter Priority When both `cursor` and `since` are provided: - The `cursor` takes precedence for delta-based synchronization - The `since` is ignored in favor of the cursor's timestamp ## Best Practices - Use `cursor` for ongoing synchronization to minimize data transfer - Use `since` for initial syncs or when resuming after a long gap - Include only necessary `custom_attributes` to optimize response size - Store the returned `cursor` persistently for reliable sync state ## Error Scenarios - **Invalid Cursor**: May return an error or fall back to full data fetch - **Expired Cursor**: Connector may return all data since the cursor's timestamp - **Unsupported Attributes**: Custom attributes not available in the connector may be ignored or cause errors depending on the connector implementation x-capability-level: read 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. ListUpdatedAccountsResponse: type: object allOf: - type: object required: - response properties: response: $ref: '#/components/schemas/UpdatedAccounts' raw_data: {} page: $ref: '#/components/schemas/Page' description: >- Response containing the main response payload, raw data, and pagination information. description: >- Response containing updated accounts information with delta synchronization support. This response model wraps the UpdatedAccounts data and provides standard response metadata including success status and any error information. 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. OAuthCredential: type: object required: - access_token properties: access_token: type: string description: The OAuth access token. x-field_type: HIDDEN x-secret: true allOf: - $ref: '#/components/schemas/OAuthAuthentication' description: OAuth access token and related authentication data. x-credential-type: oauth OAuthClientCredential: type: object required: - access_token - client_id - client_secret - scopes properties: access_token: type: string description: The OAuth access token. x-field_type: HIDDEN x-secret: true client_id: type: string description: The OAuth client id. client_secret: type: string description: The OAuth client secret. x-secret: true x-field_type: SECRET scopes: type: array items: type: string description: The OAuth scopes list. description: OAuth Client Credentials x-credential-type: oauth_client_credentials OAuth1Credential: type: object required: - consumer_key - consumer_secret - token_id - token_secret properties: consumer_key: type: string consumer_secret: type: string token_id: type: string token_secret: type: string description: |- OAuth 1.0a credential model. This auth type is not used much, handling is done per-connector. x-credential-type: oauth1 BasicCredential: type: object required: - username - password properties: username: type: string description: The username for basic auth. password: type: string description: The password for basic auth. x-secret: true x-field_type: SECRET description: Basic authentication credentials. x-credential-type: basic TokenCredential: type: object required: - token properties: token: type: string description: The token for token-based auth. x-secret: true x-field_type: SECRET description: Token-based authentication credentials. x-credential-type: token JWTCredential: type: object required: - headers - claims - secret properties: headers: allOf: - $ref: '#/components/schemas/JWTHeaders' description: The JWT headers. claims: allOf: - $ref: '#/components/schemas/JWTClaims' description: The JWT claims. secret: type: string description: The JWT secret. description: JWT credential model. x-credential-type: jwt ServiceAccountCredential: type: object required: - key - impersonation_email - tenant_id - scopes properties: service_type: allOf: - $ref: '#/components/schemas/ServiceAccountType' description: The type of service. x-field_type: HIDDEN default: google_cloud key: type: object additionalProperties: {} description: The JSON key file contents for the service account x-field_type: HIDDEN x-secret: true impersonation_email: type: string description: The email of the user to impersonate. tenant_id: type: string description: Tenant ID scopes: type: array items: type: string description: |- The scopes to request. Requested by connector. Define a default here. x-field_type: HIDDEN x-credential-type: service_account KeyPairCredential: type: object required: - key_identifier - private_key properties: key_identifier: type: string description: The identifier for the key-pair. x-field_type: HIDDEN private_key: type: string description: The private key used to authenticate with the server. x-field_type: HIDDEN x-secret: true description: Key-pair credential model. x-keygen-type: SSH x-semantic: key-pair x-credential-type: key_pair UpdatedAccounts: type: object required: - accounts properties: accounts: type: array items: $ref: '#/components/schemas/FoundAccountData' description: >- Array of account data for accounts that have been updated. Each account in this array represents an account that has been modified since the specified `since` or since the `cursor` timestamp. ## Account Data Structure Each account includes: - Standard account information (id, name, email, status, etc.) - Requested custom attributes (if specified) - Account metadata (creation date, last modified, etc.) ## Empty Responses An empty array indicates: - No accounts were updated in the specified time period - The cursor is up to date (no new changes) - The connector successfully processed the request ## Response Size Response size varies based on: - Number of updated accounts - Number of requested custom attributes - Connector-specific data richness cursor: type: string description: >- Cursor token for delta synchronization. This token represents a point in time and should be included in subsequent requests to receive only the changes that occurred since that point. - **First request**: Omit this parameter to get all available data - **Subsequent requests**: Include the `cursor` from the previous response The cursor is typically a base64-encoded string containing timestamp and other metadata needed for the delta synchronization. description: >- Response model containing updated accounts with delta synchronization support. This model extends the Delta model to include cursor information for efficient incremental synchronization. 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. OAuthAuthentication: type: object required: - access_token properties: access_token: type: string description: The OAuth access token. x-field_type: HIDDEN x-secret: true description: |- OAuth authentication model. This is a model exclusively used by standard capabilities. x-credential-type: oauth JWTHeaders: type: object required: - alg - jku - jwk - typ - kid - x5u - x5c - x5t - x5t#S256 - cty - crit properties: alg: type: string description: The JWT algorithm. jku: type: string description: JWK Set URL. jwk: type: string description: JWK. typ: type: string description: The JWT type. kid: type: string description: The JWT key ID. x5u: type: string description: The X509 URL. x5c: type: string description: The X509 certificate chain. x5t: type: string description: The X509 certificate SHA-1 thumbprint. x5t#S256: type: string description: The X509 certificate SHA-256 thumbprint. cty: type: string description: The content type of the JWT. crit: type: array items: type: string description: The JWT critical extension. description: JWT headers model. JWTClaims: type: object required: - iss - sub - aud - exp - nbf - iat - jti - act - scope - client_id - may_act properties: iss: type: string description: The issuer of the JWT. sub: type: string description: The subject of the JWT. aud: type: string description: The audience of the JWT. exp: type: integer format: int64 description: The expiration time of the JWT in seconds since the Unix epoch. nbf: type: integer format: int64 description: The not before time of the JWT in seconds since the Unix epoch. iat: type: integer format: int64 description: The issue time of the JWT in seconds since the Unix epoch. jti: type: string description: The JWT ID. act: type: string description: The Actor of the JWT. scope: type: array items: type: string description: Scopes granted to the JWT. client_id: type: string description: The client ID of the JWT. may_act: type: string description: The may_act of the JWT. description: JWT payload model representing the claims in the JWT. ServiceAccountType: type: string enum: - google_cloud - google_drive - aws FoundAccountData: type: object required: - integration_specific_id properties: integration_specific_id: type: string description: Integration specific identifier that uniquely identifies an account. x-semantic: account-id email: type: string description: The email address associated with the account. given_name: type: string description: The given name (first name) of the account holder. family_name: type: string description: The family name (last name) of the account holder. username: type: string description: The username associated with the account. user_status: allOf: - $ref: '#/components/schemas/AccountStatus' description: The current status of the account. extra_data: type: object additionalProperties: {} description: >- Additional data specific to the connector that doesn't fit into the standard fields. custom_attributes: type: object additionalProperties: type: string description: >- Custom attributes associated with the account. See the list_custom_attributes_schema capability. account_type: allOf: - $ref: '#/components/schemas/AccountType' description: The type of the account (e.g., service account or user account). description: |- A representation of a user within a connector. The fields provided here are the most commonly occurring across all connectors. For a complete list of fields specific to your connector, please refer to the [info endpoint](#tag/Describe/operation/info). x-unique-hash: - integration_specific_id 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. AccountStatus: type: string enum: - ACTIVE - INACTIVE - SUSPENDED - DEPROVISIONED - PENDING - DELETED description: Enum representing the possible statuses of an account. AccountType: type: string enum: - service - user description: Enum representing the types of accounts. ````