--- title: Lumos API Integration on Truto slug: lumos category: Compliance canonical: "https://truto.one/integrations/detail/lumos/" --- # Lumos API Integration on Truto **Category:** Compliance **Status:** Beta ## Unified APIs ### Unified User Directory API - **Groups** — Groups are a collection of users in the source application. In some applications, they might also be called Teams. - **Users** — The User object represents a User. ## MCP-ready AI tools Truto exposes 88 tools for Lumos that AI agents can call directly. - **list_all_lumos_apps** — List all apps in your Lumos company catalog. Returns a collection of app records each including id, name, and optionally custom_attributes when expanded. Supports filtering by name_search and exact_match. - **create_a_lumos_app** — Create a new app in Lumos. Returns the created app object including id and name. - **get_single_lumos_app_by_id** — Get a single Lumos app by id. Returns the app object including id, name, and optionally custom_attributes when the expand parameter is provided. Required: id. - **update_a_lumos_app_by_id** — Update domain-specific metadata overrides for a Lumos app instance. This updates the app in your domain, not the shared Lumos app catalog. Returns the updated app object including id and name. Required: id. - **list_all_lumos_apps_categories** — List all app categories available in Lumos. Returns an array of category name strings. No required parameters. - **list_all_lumos_app_settings** — Get app settings for a Lumos application. Returns the AppSettingOutput object whose field set is schema-defined in Lumos; consult the upstream docs for the field-level breakdown. Required: app_id. - **update_a_lumos_app_setting_by_id** — Update app settings for a Lumos application. Returns the updated AppSettingOutput object whose field set is schema-defined in Lumos; consult the upstream docs for the field-level breakdown. Required: app_id. - **lumos_app_settings_list_2** — Get AppStore app settings for a Lumos application using the deprecated AppStore endpoint. Returns the app settings object (attributes). Required: app_id. - **lumos_app_settings_update_2** — Update AppStore app settings for a Lumos application using the deprecated AppStore endpoint. Returns the updated app settings object (attributes). Required: app_id. - **list_all_lumos_users** — List all users in lumos. Returns: id, email, given_name, family_name, status, custom_attributes, name. Optionally filter by search_term (use exact_match to restrict to exact name/email matches) and expand the custom_attributes field via the expand parameter. - **get_single_lumos_user_by_id** — Get a single user in Lumos. Returns: id, email, given_name, family_name, status, custom_attributes. Required: id. - **list_all_lumos_user_accounts** — List accounts for a lumos user. Returns account objects including id, app_id, unique_identifier, status, and created_at. Required: user_id. - **list_all_lumos_inline_webhooks** — List all Inline Webhooks configured in Lumos. Returns: id, hook_type, name, description. Lumos supports four webhook types: Provisioning, Deprovisioning, Pre-Approval, and Request Validation. - **list_all_lumos_accounts** — List all accounts in Lumos associated with your company's apps. Returns: id, app_id, status, sources. Optionally filter by app_id, discovery date range, sources, or status; expand related app data with the expand parameter. - **list_all_lumos_group_users** — List user members belonging to a Lumos group by group ID. Returns a paginated collection of user member objects. Returns: id, email, given_name, family_name, status. Required: group_id. - **get_single_lumos_group_by_id** — Get a single group by ID in Lumos. Returns the group object including its id, name, app_id, integration_specific_id, created_at, and updated_at. Required: id. - **list_all_lumos_groups** — List groups synced from connected integrations in Lumos. Returns: id, app_id, integration_specific_id, name, description, group_lifecycle, source_app_id, created_at, updated_at. Optionally filter results by integration_specific_id, name, exact_match, or app_id. - **get_single_lumos_accounts_upload_by_id** — Get the state of an account upload job in lumos by its job ID. Returns the job state object including job_id and state. Required: id. - **create_a_lumos_accounts_upload** — Upload accounts to an app in lumos and initiate an asynchronous upload job. Returns the resulting job state object including job_id and state. Required: app_id. - **list_all_lumos_activity_logs** — List activity logs in lumos. Returns: event_hash, event_type, event_type_user_friendly, outcome, targets, actor, event_began_at, event_metadata. Optionally narrow results to a time window using the since and until date-time parameters. Max 100 records per page. - **list_all_lumos_identity_events** — List user identity events in Lumos. Returns a cursor-paginated collection of events, each including id, identity_id, and changed_fields. Optionally filter by identity_ids (user UUIDs), changed_fields (field names such as 'title' or 'team'), start_time, and end_time. - **create_a_lumos_activity_record** — Update last_login or last_activity for a given account in Lumos by posting activity record data. The request and response field schemas are not enumerated in the available source documentation; consult the Lumos API reference for the full ActivityRecordInput and ActivityRecordOutput field details. - **get_single_lumos_activity_records_job_by_id** — Get the state of an activity records post-processing job in lumos. Returns: job_id, state, id. Required: id. - **list_all_lumos_user_roles** — List roles assigned to a lumos user. Returns role objects including role_name for the specified user. Required: user_id. - **create_a_lumos_user_role** — Add a role to a lumos user, ensuring the user belongs to the specified domain. Returns a 201 response on success with no documented response body. Required: user_id, role_name. - **delete_a_lumos_user_role_by_id** — Remove a role from a lumos user, ensuring the user belongs to the specified domain. Returns an empty 204 response on success. Required: user_id, role_name. - **list_all_lumos_app_requestable_permissions** — List requestable permissions for a specific app in the lumos AppStore. Returns a collection of permission records, each including an id and permission-specific attributes. Required: app_id. - **list_all_lumos_appstore_requestable_permissions** — List requestable permissions in the lumos AppStore. Returns: id, label, app_id, app_class_id, app_instance_id, request_config. - **create_a_lumos_appstore_requestable_permission** — Create a requestable permission attached to an App in the lumos AppStore. Returns the created permission including id, label, and request_config. Required: label, and either app_id or both app_class_id and app_instance_id. - **lumos_appstore_requestable_permissions_get_2** — Get a single AppStore requestable permission by id in lumos. This is a deprecated endpoint. Returns id, label, and request_config. Required: id. - **update_a_lumos_appstore_requestable_permission_by_id** — Update an AppStore requestable permission by id in lumos. All provided fields override existing data; omitted fields are unchanged. Returns the updated permission including id, label, and request_config. Required: id. Non-updatable: request_config.request_fulfillment_config.provisioning_group. - **delete_a_lumos_appstore_requestable_permission_by_id** — Delete a requestable permission by id in lumos. Only permissions of type NATIVE can be deleted. Returns an empty 204 response on success. Required: id. - **get_single_lumos_appstore_requestable_permission_by_id** — Get a single requestable permission by id in lumos. Returns the permission record including its id, label, app_id, app_class_id, app_instance_id, request_config, and in_app_store visibility status. Required: id. - **list_all_lumos_appstore_pre_approval_rules** — List all AppStore pre-approval rules in Lumos. Returns: justification, time_based_access, id, app_id, app_class_id, app_instance_id, preapproved_groups, preapproved_users_by_attribute, preapproved_permissions, preapproval_webhooks. - **create_a_lumos_appstore_pre_approval_rule** — Create a pre-approval rule attached to an App in the Lumos AppStore. Returns: justification, time_based_access, id, app_id, app_class_id, app_instance_id, preapproved_groups, preapproved_users_by_attribute, preapproved_permissions, preapproval_webhooks. - **lumos_appstore_pre_approval_rules_get_2** — Get a single Lumos AppStore pre-approval rule by id. This endpoint path is deprecated. Returns: id. Required: id. - **update_a_lumos_appstore_pre_approval_rule_by_id** — Update a pre-approval rule in the Lumos AppStore by id. Fields present in the payload override existing values; missing fields are disregarded. Returns: justification, time_based_access, id, app_id, app_class_id, app_instance_id, preapproved_groups, preapproved_users_by_attribute, preapproved_permissions, preapproval_webhooks. Required: id. - **delete_a_lumos_appstore_pre_approval_rule_by_id** — Delete a Lumos AppStore pre-approval rule by id. Returns an empty 204 response on success. Required: id. - **get_single_lumos_appstore_pre_approval_rule_by_id** — Get a single AppStore pre-approval rule in Lumos by id. Returns: justification, time_based_access, id, app_id, app_class_id, app_instance_id, preapproved_groups, preapproved_users_by_attribute, preapproved_permissions, preapproval_webhooks, attributes. Required: id. - **list_all_lumos_appstore_apps** — List all apps in the lumos AppStore. Returns: id, app_class_id, instance_id, user_friendly_label, status, sources, allow_multiple_permission_selection, logo_url, website_url, request_instructions, description, category, links, custom_attributes. Optionally filter by app_id, name_search, exact_match, and all_visibilities. - **create_a_lumos_appstore_app** — Add an app to the lumos AppStore with given settings. Returns: custom_request_instructions, redirect_url, request_flow, provisioning, id. - **get_single_lumos_appstore_app_by_id** — Get a single AppStore app from lumos by id. Returns: id, app_class_id, instance_id, user_friendly_label, status, sources, allow_multiple_permission_selection, logo_url, website_url, request_instructions, description, category, links, custom_attributes. Required: id. - **delete_a_lumos_appstore_app_by_id** — Remove an app from the lumos AppStore by id. Returns an empty 204 response on success. Required: id. - **get_single_lumos_appstore_access_request_by_id** — Get a lumos access request by id. Returns the access request object including id, status, target_user_id, requester_user_id, tasks, and custom_fields. Required: id. - **delete_a_lumos_appstore_access_request_by_id** — Cancel a lumos access request by id. Returns an empty 204 response on success. Required: id. - **create_a_lumos_appstore_access_request** — Create a lumos access request for a specific appstore permission. Returns: id, app_id, app_name, requester_user, target_user, supporter_user, status, notes, expires_at, expiration_in_seconds, requestable_permissions, requested_at, tasks, custom_fields, target_user_id, requester_user_id. - **list_all_lumos_appstore_access_requests** — List all lumos access requests for the current organization. Returns: id, app_id, app_name, requester_user, target_user, supporter_user, status, notes, expires_at, expiration_in_seconds, requestable_permissions, requested_at, tasks, custom_fields, target_user_id, requester_user_id, created_at. Filter by target_user_id, requester_user_id, user_id, or statuses; sort ascending or descending by… - **list_all_lumos_access_policies** — List all access policies in lumos, sorted by created time descending. Returns: name, business_justification, id, status, is_enabled, apps, access_condition, is_everyone_condition, created_at, updated_at. Optionally filter results by policy name (case insensitive). - **create_a_lumos_access_policy** — Create a new access policy in lumos. Returns the created access policy object including id, name, status, created_at, and updated_at. - **get_single_lumos_access_policy_by_id** — Get a single access policy by id in lumos. Returns: name, business_justification, id, status, is_enabled, apps, access_condition, is_everyone_condition, created_at, updated_at. Required: id. - **update_a_lumos_access_policy_by_id** — Update an access policy by id in lumos. Returns the updated access policy object including id, name, status, created_at, and updated_at. Required: id. - **delete_a_lumos_access_policy_by_id** — Delete an access policy by id in lumos. Returns an empty 204 response on success. Required: id. - **list_all_lumos_access_reviews** — List access reviews for your organization in lumos. Returns each review's id, status, and apps. Page size is capped at 100 per request. - **create_a_lumos_access_review** — Create a new access review campaign in lumos. Returns: access_review, errors, id, status, apps. If apps are provided the review starts in IN_PREPARATION while account and entitlement snapshots are taken, then transitions automatically to IN_PROGRESS once snapshotting completes; without apps it starts directly in IN_PROGRESS. - **get_single_lumos_access_review_by_id** — Get a lumos access review by id. Returns: id, name, status, creation_path, owner_id, created_by_id, deadline_at, started_at, completed_at, target_launch_date, recurrence_config, recurrence_days_frequency, created_at, updated_at, apps. Required: id. - **update_a_lumos_access_review_by_id** — Update an existing lumos access review campaign by id. Returns: id, name, status, creation_path, owner_id, created_by_id, deadline_at, started_at, completed_at, target_launch_date, recurrence_config, recurrence_days_frequency, created_at, updated_at, apps. Required: id. Top-level fields are editable on any non-COMPLETED review; apps[].scope_filters edits are only accepted while the review is in… - **delete_a_lumos_access_review_by_id** — Soft-delete a lumos access review campaign by id. Returns an empty 204 response on success. Required: id. Fails with 400 if a review duplication is currently in progress. - **create_a_lumos_access_review_app** — Add apps to an existing lumos access review campaign. Allowed on any review not yet COMPLETED; invalid or duplicate domain app UUIDs result in soft errors returned in the errors array rather than raising an exception. Returns: added_apps, errors. Required: access_review_id. - **delete_a_lumos_access_review_app_by_id** — Soft-delete an app from a lumos access review campaign by id. Returns an empty 204 response on success. Required: access_review_id, id. Fails with 400 if the review is already COMPLETED. - **list_all_lumos_access_reviews_scope_options** — List available scope filter option groups for a domain app or ARDA in Lumos. Returns scope filter groups, each including name, items (scope filter entries capped at 1000 per group), truncated (true when the bucket exceeds the cap), and entitlement_type_label (for ACCOUNT_ENTITLEMENT groups, e.g. 'Roles', 'Groups'). Copy an item's value and name verbatim into scope_filters on access review… - **list_all_lumos_knowledge_contexts** — List knowledge context entries in lumos with optional filters and cursor pagination. Returns a collection of entries where each item includes id, title, product_scopes, created_at, and updated_at. Optional: title_search, product_scopes. - **create_a_lumos_knowledge_context** — Create a new knowledge context entry in lumos. Returns the created entry including id, title, product_scopes, created_at, and updated_at. Optionally include a file attachment — omit the file field to create an entry without one. - **get_single_lumos_knowledge_context_by_id** — Get a single lumos knowledge context entry by id. Returns id, title, product_scopes, created_at, and updated_at. Required: id. - **update_a_lumos_knowledge_context_by_id** — Patch an existing lumos knowledge context entry by id. Only supplied fields are updated; tag and scope lists replace existing values entirely. Returns the updated entry including id, title, product_scopes, created_at, and updated_at. Required: id. - **delete_a_lumos_knowledge_context_by_id** — Archive (soft-delete) a lumos knowledge context entry by id. The entry is marked ARCHIVED and no longer appears in list results. Returns an empty 204 response on success. Required: id. - **list_all_lumos_vendor_agreements** — List all vendor agreements for your company in lumos. Returns vendor agreement records from the paginated items collection. Returns: id, vendor, label, start_date, end_date, opt_out_date, renewal_stage, pricing_model, contract_length_months, projected_annualized_cost, renewal_owners, total_contract_cost, line_items, custom_attributes. - **update_a_lumos_vendor_agreement_custom_attribute_by_id** — Update a custom attribute attached to a vendor agreement in Lumos. Returns the updated custom attribute record including id and label. Required: vendor_agreement_id, id. - **create_a_lumos_found_document** — Upload a newly discovered document (e.g. Order Form, Quote) to Lumos for review. Sends document metadata and file URLs to Lumos and returns a 200 acknowledgment with no documented response body fields. Required: unique_identifier, files. - **create_a_lumos_order** — Upload a newly discovered order document (e.g. Order Form, Quote) to Lumos. Accepts a required JSON body conforming to the OrderInput schema; the individual field definitions are not enumerated in the available source documentation. Returns a 201 status on success with no documented response body fields. - **list_all_lumos_tasks** — List lumos tasks visible to the current user. Returns task objects including id, task_type, task_category, status, and product_area. Filter by task_category, status, product_area, search text, or access_request_id; pass expand=actions or expand=assignees to hydrate those fields on each result. Admins may pass show_all_tasks=true to list tasks across the entire domain. - **lumos_tasks_get_2** — Get a lumos task by id using the deprecated endpoint; prefer the non-deprecated get method instead. Returns task details including id, task_type, task_category, status, product_area, actions, assignees, and comments. Required: id. - **lumos_tasks_attach_comment** — Add a comment to a lumos task. The request body accepts an AddCommentInput payload; the specific body fields are not enumerated in the source documentation. Returns a 201 response on success with no documented response body. Required: id. - **lumos_tasks_complete** — Complete a lumos task, transitioning it to COMPLETED status. For approval tasks (task_category=APPROVAL), this performs the approve action on behalf of the caller, who must be an assignee or domain admin. Tasks with multiple possible completion actions should use the perform-action endpoint instead. Returns an empty 204 response on success. Required: id. - **get_single_lumos_task_by_id** — Get a single lumos task by id. Returns task details including id, task_type, task_category, status, product_area, app, target_user, created_at, actions, assignees, comments, and access_request_id. Pass expand=actions, expand=assignees, or expand=comments to hydrate those nested fields. Required: id. - **lumos_tasks_perform_action** — Perform an action on a Lumos task by task id. Returns an empty 204 response on success. Required: id. - **lumos_tasks_reassign** — Reassign a Lumos task to another user by task id. Returns an empty 204 response on success. Required: id. - **lumos_tasks_dismiss** — Dismiss a Lumos task by task id. Returns an empty 204 response on success. Required: id. - **list_all_lumos_task_actions** — List all actions associated with a specific task in Lumos. Returns action records including id, created_at, and updated_at. Required: task_id. - **create_a_lumos_task_perform_action** — Perform a custom workflow action on a lumos task (deprecated endpoint). Use this only when the task exposes non-standard actions beyond approve/deny; discover available actions with GET /tasks/{task_id}/actions first, then supply the returned action_type in the request body. The optional transition_to field is inferred when the action has exactly one possible target status. Returns an empty 204… - **create_a_lumos_task_reassign** — Reassign a task in Lumos using this deprecated endpoint. Returns an empty 204 response on success. Required: task_id. - **create_a_lumos_task_dismise** — Dismiss a Lumos task by transitioning it to the DISMISSED state, acting as a deny/reject for approval tasks or a cancellation for non-approval tasks. Returns an empty 204 response on success. Required: task_id. - **list_all_lumos_arts** — Get Lumos ASCII art to verify the API is working. Returns a plain text string containing ASCII art. No parameters required. - **list_all_lumos_info** — Get current git revision information from Lumos. Returns an unstructured JSON object whose response fields are not enumerated in the API schema (the response shape is deployment-specific and not documented by the upstream API). - **create_a_lumos_airbase_purchase_request_approved** — Send an Airbase purchase request approved webhook event for a specific domain app, triggering workflow milestone transition processing. Returns an opaque acknowledgment response whose shape is not enumerated by the upstream API. Required: domain_app_uuid. - **create_a_lumos_vendr_request_completed** — Send a Vendr request completed webhook event to Lumos for a specific domain app. Accepts an arbitrary JSON object representing the Vendr event payload. Returns an opaque webhook acknowledgment response. Required: domain_app_uuid. - **list_all_lumos_appstore_app_settings** — List settings for a Lumos AppStore app. Returns the app settings object with app-specific configuration fields whose shape depends on the app's configuration in Lumos. Required: app_id. - **update_a_lumos_appstore_app_setting_by_id** — Update settings for a Lumos AppStore app via a partial PATCH. Returns the updated app settings object with app-specific configuration fields whose shape depends on the app's configuration in Lumos. Required: app_id. - **list_all_lumos_current_user** — Get the current authenticated user in Lumos. Returns the authenticated user's profile including id, email, created_at, and updated_at. ## How it works 1. **Link your customer's Lumos account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Lumos.** The Proxy API is a 1-to-1 mapping of the Lumos API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Publish your app to the Lumos AppStore** — B2B SaaS companies can programmatically register their product, logos, and role definitions in a mutual customer's Lumos catalog so end users can self-serve access without IT tickets. - **Automate Joiner/Mover/Leaver provisioning** — HRIS and identity platforms can listen to Lumos identity events and approved access tasks to automatically provision, adjust, or revoke user accounts as employees change roles. - **Pull continuous compliance evidence for audits** — GRC and compliance platforms can ingest Lumos access reviews, access policies, and activity logs to serve as immutable, auditor-ready evidence of SOC 2 or SOX access controls. - **Hand off procurement contracts into governance** — Spend management and procurement tools can push executed vendor agreements and orders into Lumos so newly purchased SaaS is immediately governed for SSO, access, and spend tracking. - **Sync approval tasks with external ticketing workflows** — ITSM tools can list, complete, reassign, or dismiss Lumos tasks so approval decisions made in an external ticketing system reflect accurately in Lumos access workflows. ## What you can build - **AppStore self-publishing flow** — Let your customers install your app into Lumos with one click, automatically creating the AppStore app, requestable permissions, and pre-approval rules. - **Bulk user & account sync** — Sync your product's current user base into Lumos using accounts upload jobs, keeping account ownership and license usage accurate for governance. - **Identity event–driven Mover workflows** — Subscribe to Lumos identity events to detect title, team, or manager changes and automatically trigger downstream provisioning or deprovisioning in your app. - **Access review evidence dashboard** — Pull access reviews, policies, and activity logs into your GRC product to show customers a live view of audit campaign status and reviewer decisions. - **Procurement-to-governance handoff** — Push signed orders and found documents into Lumos and trigger workflow endpoints so IT is alerted the moment a new vendor contract is executed. - **Bi-directional task and approval sync** — Mirror Lumos access request tasks in your ticketing UI, letting users comment, perform actions, complete, reassign, or dismiss tasks without leaving your product. ## FAQs ### How does authentication work for the Lumos integration? Truto handles the Lumos auth handshake and token storage for you. Your end users connect their Lumos tenant through Truto's managed auth flow, and you call Lumos endpoints using Truto's unified credentials layer — no need to manage keys or refresh logic yourself. ### Can I sync users and groups from Lumos through a unified schema? Yes. Lumos is mapped to Truto's Unified User Directory API, so users and groups are available in a normalized schema. You can also drop down to native Lumos endpoints like list_all_lumos_users, list_all_lumos_groups, and list_all_lumos_group_users when you need Lumos-specific fields. ### Which Lumos workflows can I automate via the API? Truto exposes the full Lumos surface needed for governance workflows: AppStore app and permission publishing, pre-approval rules, access reviews, access policies, tasks (complete, perform action, reassign, dismiss), accounts uploads, identity events, activity logs, vendor agreements, orders, and knowledge contexts. ### How do I keep data fresh — polling or webhooks? You can poll list endpoints like list_all_lumos_tasks, list_all_lumos_identity_events, and list_all_lumos_activity_logs on a schedule through Truto. Lumos also supports inline webhooks (list_all_lumos_inline_webhooks) which Truto can help you consume for near real-time updates on approvals and lifecycle events. ### Can I trigger provisioning decisions from my product back into Lumos? Yes. You can act on Lumos tasks programmatically using lumos_tasks_complete, lumos_tasks_perform_action, lumos_tasks_reassign, and lumos_tasks_dismiss, letting your product drive Lumos approval state instead of just reading from it. ### How does Truto handle Lumos-specific quirks like pagination and rate limits? Truto normalizes pagination across Lumos list endpoints and manages retries and backoff on rate-limited responses. You get a consistent request/response shape whether you're pulling activity logs, access reviews, or AppStore configuration. ## Related reading - [Connect Lumos to Claude: Automate Access Reviews & Identity Logs](https://truto.one/blog/connect-lumos-to-claude-automate-access-reviews-and-identity-logs/) — Learn how to connect Lumos to Claude using Truto's MCP Server. A technical guide to automating access reviews, identity logs, and JIT access with AI agents. - [Connect Lumos to ChatGPT: Manage app access, users, and permissions](https://truto.one/blog/connect-lumos-to-chatgpt-manage-app-access-users-and-permissions/) — Learn how to connect Lumos to ChatGPT using a managed MCP server. Automate access reviews, user provisioning, and vendor agreements with AI agents. - [Connect Lumos to AI Agents: Orchestrate SaaS tasks and vendor data](https://truto.one/blog/connect-lumos-to-ai-agents-orchestrate-saas-tasks-and-vendor-data/) — Learn how to connect Lumos to AI Agents using Truto's /tools endpoint. Fetch tools programmatically and orchestrate complex IT access and vendor workflows.