# Lumos Documentation > Lumos is the first Autonomous Identity Platform that automatically discovers and manages access across all your apps. It goes beyond traditional IGA by delivering: Complete Visibility: Uncover every app, identity and permission to see your entire access landscape. Actionable Insights: Lumos pinpoints the biggest security risks and costs inefficiencies, giving teams clear direction to reduce access sprawl effectively. Full Automation: Automate the whole identity lifecycle from joiner-mover-leaver workflows to JIT access to access reviews. Adaptive Systems: Keep RBAC policies up-to-date with AI as your organization evolves. Append .md to any documentation page URL to get its markdown version. ## Guides - [🏁 Getting Started](https://developers.lumos.com/docs/getting-started.md): Empower secure access in minutes—explore, integrate, and automate with the Lumos Autonomous Identity Platform. - [🚀 Quick Start](https://developers.lumos.com/docs/quick-start.md): Launch your first Lumos integration in minutes—authenticate, create, and manage accounts - [🌀 Core Concepts](https://developers.lumos.com/docs/core-concepts.md): Explore the foundation of the Lumos platform—discover how it unifies identity, accounts, and permissions data for automated access management - [👥 Object Model](https://developers.lumos.com/docs/object-model.md): Understanding the Lumos object model - [🔑 Modeling Permissions](https://developers.lumos.com/docs/modeling-permissions.md): How to model permissions in Lumos - [🏗️ Reference Architecture](https://developers.lumos.com/docs/reference-architecture.md): Lumos Enterprise Architecture and Deployment Strategy - [🧩 Integration Patterns](https://developers.lumos.com/docs/integration-patterns-1.md): Seamlessly unify identity and access across SaaS, on-premise, legacy and custom systems—discover Lumos integration patterns for any scenario - [☁️ SaaS](https://developers.lumos.com/docs/saas-integrations.md): Enterprise-ready connectors enabling automated access management for cloud-based applications - [🔄 SCIM](https://developers.lumos.com/docs/scim-1.md): Standards-based identity synchronization framework supporting automated access provisioning across SCIM 2.0-compatible systems. - [🗂️ Directory](https://developers.lumos.com/docs/directory-integration.md):

Secure and scalable connectivity solution for Active Directory and LDAP systems across hybrid environments. - [🛢️ Database (JDBC)](https://developers.lumos.com/docs/database-integration-jdbc.md):

Direct database connectivity supporting identity governance through standardized JDBC protocols with comprehensive security controls. - [🔌 Connector SDK](https://developers.lumos.com/docs/custom-connector-sdk.md):

Extensible development framework for building tailored integrations with custom apps/systems while maintaining enterprise governance standards. - [📄 Flat File (CSV)](https://developers.lumos.com/docs/csv-import.md):

Robust data ingestion capability supporting bulk identity operations - [🌐 REST API](https://developers.lumos.com/docs/rest-api-1.md):

Comprehensive programmatic interface enabling custom automation and integration workflows through standard REST protocols. - [🤖 Webhooks](https://developers.lumos.com/docs/webhooks.md):

Event-driven integration mechanism supporting real-time identity lifecycle management through secure webhook notifications. - [🤹 Manual Tasks](https://developers.lumos.com/docs/manual-tasks.md): Structured workflow system for managing human-in-the-loop processes with full audit and compliance capabilities. - [🎫 ITSM Integration](https://developers.lumos.com/docs/itsm-integration.md): Seamless connection between identity governance and IT service management platforms ensuring consistent service delivery and compliance. - [🔌 Connector SDK](https://developers.lumos.com/docs/connector-sdk-1.md):

Guide to how Lumos Connectors work and how you can build one using the Connector SDK - [🏛️ On-Premise Agent](https://developers.lumos.com/docs/on-premise-agent-1.md): Secure bridge between your internal systems and the Lumos Autonomous Identity Platform - [📦 Installation](https://developers.lumos.com/docs/installation.md): Lumos On-Premise Agent Installation on Windows and Containers - [📜 Adding Additional CA Certificates](https://developers.lumos.com/docs/adding-additional-ca-certificates.md) - [♾️ High-Availability Architecture](https://developers.lumos.com/docs/high-availability-architecture.md): Deploy Lumos Agent for Redundancy - [🧬 On-Premise Agent Clustering](https://developers.lumos.com/docs/on-premise-agent-clustering.md): Support for Multi-Network On-Premise Agent Clustering - [🗂️ Active Directory Connector](https://developers.lumos.com/docs/active-directory-connector.md):

How to configure your Active Directory connector for fetching user and groups - [📁 LDAP Connector](https://developers.lumos.com/docs/ldap-connector.md): How to configure your LDAP Connector for fetching users and groups - [🛢️ Database (JDBC) Connector](https://developers.lumos.com/docs/database-jdbc.md): How to configure your JDBC connector for fetching users and access data from any database - [📄 Flat File Connector](https://developers.lumos.com/docs/flatfile-connector.md): How to configure your Flatfile Connector for fetching users and access data - [Configuring Read and Write Optimized Agents](https://developers.lumos.com/docs/configuring-read-and-write-optimized-agents.md) - [Validating Your On-Premise Agent Deployment](https://developers.lumos.com/docs/validating-your-on-premise-agent-deployment.md) - [Agent Quick Start Guide](https://developers.lumos.com/docs/quick-start-guide.md): Install the Lumos On-Premise Agent, deploy stock and custom connectors, cluster across networks, run multiple agents for high availability, and validate your deployment. - [MCP](https://developers.lumos.com/docs/mcp.md): This guide explains how to connect an MCP-compatible AI client to Lumos MCP and verify that the user can discover and run Lumos tools. - [Lumos Admin MCP](https://developers.lumos.com/docs/lumos-admin-mcp.md): This guide explains how to connect an MCP-compatible AI client to the Lumos Admin MCP server, choose the toolsets you need, and run your first admin request. - [Lumos MCP: Security & Authentication](https://developers.lumos.com/docs/mcp-authsecurity-for-iam.md) - [Managing Integrations](https://developers.lumos.com/docs/managing-integrations.md) - [Managing Integrations via Terraform](https://developers.lumos.com/docs/managing-integrations-via-terraform.md): The Lumos Terraform provider lets you manage your app integrations as code. You declare each integration as a `lumos_app` resource, then version, review, and apply it like any other infrastructure — instead of clicking through the Lumos UI. This guide is the Terraform counterpart to Managing Integrations via API. - [Managing Integrations via API](https://developers.lumos.com/docs/managing-integrations-via-api.md): The Integrations API lets you connect and manage your app integrations programmatically - the same connections you'd otherwise set up by hand in the Lumos UI. Use it to wire up integrations from a script, a CI pipeline, or an infrastructure-as-code tool. - [Syncing Integrations via API](https://developers.lumos.com/docs/syncing-integrations-via-api.md): The sync endpoint lets you trigger an integration sync on demand — a fresh pull of an app's accounts and entitlements into Lumos — from a script, a CI pipeline, or a scheduler. You don't need to manage the integration's connection through the API to use it: it works for integrations connected in the Lumos UI, via the Integrations API, or via Terraform. - [🔌 Connector SDK](https://developers.lumos.com/docs/connector-sdk.md):

Sample integration built using Connector SDK - [Lumos Connector Quick Reference Guide](https://developers.lumos.com/docs/lumos-connector-quick-reference-guide.md) - [Building a Lumos Connector: Step-by-Step Tutorial](https://developers.lumos.com/docs/building-a-lumos-connector-step-by-step-tutorial.md) - [Mock API Server for Testing Lumos Connectors](https://developers.lumos.com/docs/mock-api-server-for-testing-lumos-connectors.md) - [🗂️ Directory (AD)](https://developers.lumos.com/docs/directory-ad.md):

Sample AD Queries to Import Subset of Users and Groups - [🛢️ Database (JDBC)](https://developers.lumos.com/docs/jdbc.md):

Sample SQL Queries - [Microsoft SQL Server](https://developers.lumos.com/docs/microsoft-sql-server.md):

Discover system accounts and their permissions - [Oracle DB](https://developers.lumos.com/docs/oracle-db.md):

Discover system accounts and their permissions - [PostgreSQL](https://developers.lumos.com/docs/postgresql.md):

Discover system accounts and their permissions - [MySQL](https://developers.lumos.com/docs/mysql.md):

Discover system accounts and their permissions - [MongoDB](https://developers.lumos.com/docs/mongodb.md):

Discover system accounts and their permissions - [Snowflake](https://developers.lumos.com/docs/snowflake.md):

Discover system accounts and their permissions - [Databricks](https://developers.lumos.com/docs/databricks.md):

Discover system accounts and their permissions - [🎲 Sample Application Database](https://developers.lumos.com/docs/sample-application.md):

Discover and manage application accounts and their permissions - [📄 Flat File (CSV)](https://developers.lumos.com/docs/csv-file.md):

Sample Flat File Template for Importing Identity and Access Data - [🌐 REST API](https://developers.lumos.com/docs/rest-api.md):

Sample REST API to Create Application and Upload Accounts - [🔧 Terraform](https://developers.lumos.com/docs/terraform.md):

Create a Lumos requestable permission linked to a specified security group and application - [📘 Product Documentation](https://developers.lumos.com/docs/product-documentation.md): Organized by operational workflows of Identity Governance and Non-Human Identity Management projects - [🛡️ Trust Center](https://developers.lumos.com/docs/trust-center.md): The Lumos Trust Page is a hub for information on security and compliance. - [On Prem Agent Changelog](https://developers.lumos.com/docs/on-prem-agent-changelog.md): The changelog for the Lumos On Prem Agent - [Active Directory Changelog](https://developers.lumos.com/docs/activedirectory-changelog.md) - [LDAP Changelog](https://developers.lumos.com/docs/ldap-changelog.md) - [Retool Changelog](https://developers.lumos.com/docs/retool-changelog.md) - [Tableau Changelog](https://developers.lumos.com/docs/tableau-changelog.md) - [JDBC Changelog](https://developers.lumos.com/docs/jdbc-changelog.md) - [1Password - Groups Changelog](https://developers.lumos.com/docs/one-password-changelog.md) - [1Password - Admin Changelog](https://developers.lumos.com/docs/one-password-roles-changelog.md) - [Delinea Secret Server Changelog](https://developers.lumos.com/docs/delinea-secretserver-changelog.md) - [SCIM Connector Changelog](https://developers.lumos.com/docs/scim-changelog.md) - [Flatfile Connector (On Prem) Changelog](https://developers.lumos.com/docs/on-prem-flatfile-changelog.md) - [🔧 Terraform Provider](https://developers.lumos.com/docs/terraform-provider.md) - [🔗 Postman Collection](https://developers.lumos.com/docs/postman-collection.md): Easily test Lumos API with our Postman collection - [🚦 Tines Integration](https://developers.lumos.com/docs/tines-integration.md): Automate with Tines using pre-built workflows for Lumos - [Command Line Interface](https://developers.lumos.com/docs/cli.md): Welcome to the Lumos CLI documentation. - [Authentication](https://developers.lumos.com/docs/cli-authentication.md): Authenticating the Lumos CLI - [Contributing](https://developers.lumos.com/docs/cli-contributing.md): Authenticating the Lumos CLI - [Installation](https://developers.lumos.com/docs/cli-installation.md): Installing the Lumos CLI - [Reference](https://developers.lumos.com/docs/cli-reference.md): Lumos CLI Reference - [Examples](https://developers.lumos.com/docs/cli-examples.md): Lumos CLI Examples ## API Reference - [💫 Build & Extend with Lumos](https://developers.lumos.com/reference/overview.md): Harness Lumos APIs to automate access management, enforce compliance, and build powerful integrations. - [⚡ Lumos API](https://developers.lumos.com/reference/lumos-api.md) - [Create Access Review](https://developers.lumos.com/reference/createaccessreview.md): Create a new access review campaign. The review's initial status depends on whether apps are provided: - **With apps**: the review starts in `IN_PREPARATION` while account and entitlement snapshots are taken. Status automatically transitions to `IN_PROGRESS` once snapshotting completes. - **Without apps**: the review is created directly in `IN_PROGRESS`. Poll `GET /access_reviews/{id}` to observe the status transition. To add apps after creation, use `POST /access_reviews/{id}/apps` (allowed on any status except `COMPLETED`). - [List Access Reviews](https://developers.lumos.com/reference/listaccessreviews.md): List access reviews for your organization. Paginated via standard `page` + `size` query params — `size` is capped at 100; requests over the cap return 422. - [Add Apps To Access Review](https://developers.lumos.com/reference/addappstoaccessreview.md): Add apps to an existing access review. Allowed on any review that is not yet `COMPLETED`. Soft-errors on invalid or duplicate domain app UUIDs — per-app failures are returned in the `errors` array rather than raising. - [Delete Access Review](https://developers.lumos.com/reference/deleteaccessreview.md): Soft-delete an access review campaign. Fails with 400 if a review duplication is currently in progress. - [Get Access Review](https://developers.lumos.com/reference/getaccessreview.md): Get an access review by ID. - [Update Access Review](https://developers.lumos.com/reference/updateaccessreview.md): Update an existing access review campaign. Top-level fields are editable on any review that is not yet `COMPLETED`. Per-app (`apps[].scope_filters`) edits are only accepted while the ARDA is still in `IN_PREPARATION` or `ASSIGNING_REVIEWERS` status. - [Delete Access Review App](https://developers.lumos.com/reference/deleteaccessreviewapp.md): Soft-delete an app from an access review campaign. Fails with 400 if the review is already `COMPLETED`. - [Get Scope Options Endpoint](https://developers.lumos.com/reference/getscopeoptions.md): Get available scope filter options for a domain app or ARDA. To use these in `scope_filters` on a create/edit request, copy an item's `value` (and `name`) verbatim — `value` is the machine-matchable identifier, while `label` is display-only. Posting a `label` as a `value` (or any value not present here) is rejected. ACCOUNT_ENTITLEMENT groups are split per `entitlement_type_label` (e.g. 'Roles', 'Groups'), with each group's `items` capped at 1000 entitlement labels. Groups whose underlying bucket exceeds the cap set `truncated: true` so callers know some valid labels are not present in the response. - [List Tasks](https://developers.lumos.com/reference/list_tasks_tasks_get.md): List tasks visible to the current user. Combine `task_category`, `product_area`, and `status` to find the tasks you care about: - **Pending access-request approvals**: `GET /tasks?task_category=APPROVAL&product_area=APPSTORE&status=PENDING` 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 whole domain rather than just the caller's assigned set. - [Get Task](https://developers.lumos.com/reference/get_task_tasks__task_id__get.md): Get a task by ID. - [Get Task Actions](https://developers.lumos.com/reference/get_task_actions_tasks__task_id__actions_get.md): Get available actions for a task. - [Perform Task Action](https://developers.lumos.com/reference/perform_task_action_tasks__task_id__perform_action_post.md): **Perform a custom action on a task** — the generic escape hatch for tasks that expose workflow-specific actions beyond approve/deny. For approval tasks, prefer `POST /tasks/{task_id}/complete` or `POST /tasks/{task_id}/dismiss` — those endpoints are simpler and do not require discovering the action type. Use this endpoint only when the task exposes custom actions. Discover the available actions for a task with `GET /tasks/{task_id}/actions`; each returned action includes an `action_type` (the value to pass in this request body) and the status transitions it can produce. `transition_to` is optional — if the action has exactly one possible target status, it is inferred. Pass it explicitly when an action can transition to more than one status. Responses: - `204 No Content` — action performed. - `400 Bad Request` — unknown action type or invalid transition. - `403 Forbidden` — caller is not authorized to act on the task. - `409 Conflict` — task is already in the requested status. - [Reassign Task](https://developers.lumos.com/reference/reassign_task_tasks__task_id__reassign_post.md): Reassign a task. - [Add Task Comment](https://developers.lumos.com/reference/add_task_comment_tasks__task_id__comments_post.md): Add a comment to a task. - [Complete Task](https://developers.lumos.com/reference/complete_task_tasks__task_id__complete_post.md): **Complete a task** — transition any task to `COMPLETED` by applying its unique completion action. For approval tasks this is the "approve" primitive. Common uses: - **Approve an access request** (task with `task_category=APPROVAL` and `product_area=APPSTORE`). - **Mark a non-approval task done** when it exposes exactly one action that transitions to `COMPLETED` (e.g. acknowledging a manual provisioning step). Tasks with multiple possible completion actions should use `POST /tasks/{task_id}/perform-action` instead. This endpoint resolves the unique action on the task that transitions it to `COMPLETED` and applies it on behalf of the caller. The caller must be an assignee of the task (or a domain admin). There is no request body. Responses: - `204 No Content` — task completed. - `403 Forbidden` — caller is not authorized to act on the task. - `409 Conflict` — task is already in the requested status (safe to treat as idempotent). - `404 Not Found` — task does not exist in this domain, or the Tasks API is not enabled. To deny instead of approve, use [`POST /tasks/{task_id}/dismiss`](#dismiss-task). For tasks that expose custom workflow actions (not approvals), use [`POST /tasks/{task_id}/perform-action`](#perform-task-action). - [Dismiss Task](https://developers.lumos.com/reference/dismiss_task_tasks__task_id__dismiss_post.md): **Dismiss a task** — transition any task to `DISMISSED` by applying its unique dismissal action. For approval tasks this is the "deny / reject" primitive; for non-approval tasks it cancels the task without performing its work. Common uses: - **Deny an access request**. - **Cancel a non-approval task** (e.g. dismiss an error task once the underlying issue is handled out-of-band). Tasks with multiple possible dismissal actions should use `POST /tasks/{task_id}/perform-action` instead. Resolves the unique action on the task that transitions it to `DISMISSED` and applies it on behalf of the caller. The caller must be an assignee of the task (or a domain admin). There is no request body. Responses: - `204 No Content` — task dismissed. - `403 Forbidden` — caller is not authorized to act on the task. - `409 Conflict` — task is already in the requested status. - `404 Not Found` — task does not exist in this domain, or the Tasks API is not enabled. To approve instead of deny, use [`POST /tasks/{task_id}/complete`](#complete-task). - [List Knowledge Context](https://developers.lumos.com/reference/listknowledgecontext.md): List knowledge entries for the caller's domain with optional filters and cursor pagination. Pass the `next_page_token` value from the previous response back as the `page_token` query parameter to fetch the next page. When `next_page_token` is `null`, the current page is the last one. - [Create Knowledge Context](https://developers.lumos.com/reference/createknowledgecontext.md): Create a new knowledge entry in the caller's domain. Send as `multipart/form-data`. The `file` field is optional — omit it to create an entry without an attachment. - [Get Knowledge Context](https://developers.lumos.com/reference/getknowledgecontext.md): Get a single knowledge entry by ID. - [Update Knowledge Context](https://developers.lumos.com/reference/updateknowledgecontext.md): Patch an existing knowledge entry. Only supplied (non-empty) fields are updated. Tag and scope lists replace existing values entirely — they do not append. Send as `multipart/form-data`. To replace the attached file, include a `file` field. To remove the existing file without uploading a new one, set `clear_attachment=true`. - [Delete Knowledge Context](https://developers.lumos.com/reference/deleteknowledgecontext.md): Archive (soft-delete) a knowledge entry. The entry is marked ARCHIVED and will no longer appear in list results. This action is reversible at the database level. - [Get App](https://developers.lumos.com/reference/getapp-1.md): Get an app by id. - [Get Apps](https://developers.lumos.com/reference/listapps-1.md): List all of your company's apps. - [Get App Categories](https://developers.lumos.com/reference/getappcategories-1.md): Get app categories. - [Create App](https://developers.lumos.com/reference/createapp-1.md): Create a new custom app, or connect an integration app. With a `name`/`category`/`description` body this creates a custom app. With an `app_class_id` body it connects the integration identified by `app_class_id` using the credentials in `auth` — integrations that validate in-band connect immediately and trigger an initial sync, while integrations that require browser consent are finished in the Lumos UI. Custom apps and integrations created here are both marked `connection_source=API`; list your API-managed apps with `GET /apps?connection_source=API&disconnected=false`. - [Update App](https://developers.lumos.com/reference/updateapp-1.md): Update domain-specific app metadata overrides. This updates the app instance in your domain, not the shared Lumos app catalog. - [Get User](https://developers.lumos.com/reference/getuser-1.md): Get user by id. - [Get Users](https://developers.lumos.com/reference/listusers-1.md): List all of your company's users. - [Get User Roles](https://developers.lumos.com/reference/get_user_roles_users__user_id__roles_get.md): Get the roles assigned to a specific user, ensuring the user belongs to the specified domain. - [Add Role To User](https://developers.lumos.com/reference/add_role_to_user_users__user_id__roles__role_name__post.md): Add a role to a specific user, ensuring the user belongs to the specified domain. - [Remove Role From User](https://developers.lumos.com/reference/remove_role_from_user_users__user_id__roles__role_name__delete.md): Remove a specific role from a user, ensuring the user belongs to the specified domain. - [Get Identity Events](https://developers.lumos.com/reference/getidentityevents.md): Get user identity events. - [Get Accounts](https://developers.lumos.com/reference/getaccounts.md): Get all accounts associated with apps at your company. - [Get User Accounts](https://developers.lumos.com/reference/getuseraccounts.md): Get a list of Accounts for this user - [Create Accounts](https://developers.lumos.com/reference/postaccounts-1.md): Upload accounts to an app. - [Get Upload Job State](https://developers.lumos.com/reference/getuploadjobstate-1.md): Get state of an account upload job. - [Update Activity Records](https://developers.lumos.com/reference/activityrecords-1.md): Update the last_login or last_activity for a given account. - [Get Activity Records Job State](https://developers.lumos.com/reference/getactivityrecordsjobstate-1.md): Get the state of an activity records post-processing job. - [Get Group](https://developers.lumos.com/reference/getgroup-1.md): Get group by ID. - [Get Groups](https://developers.lumos.com/reference/getgroups-1.md): Get groups synced from connected integrations - [Get Group Membership](https://developers.lumos.com/reference/getgroupmembership-1.md): Get user members by group ID. - [Get Inline Webhooks](https://developers.lumos.com/reference/get_inline_webhooks_inline_webhooks_get-1.md): Get available webhooks - [Get Activity Logs](https://developers.lumos.com/reference/getactivitylogs-1.md): Get activity logs. - [Get Access Policy](https://developers.lumos.com/reference/getaccesspolicy.md): Get an access policy by ID. - [Get Access Policies](https://developers.lumos.com/reference/getaccesspolicies.md): Get all access policies. Results are sorted by created time descending by default. - [Create Access Policy](https://developers.lumos.com/reference/createaccesspolicy.md): Create a new access policy. - [Update Access Policy](https://developers.lumos.com/reference/updateaccesspolicy.md): Update an access policy by ID. - [Delete Access Policy](https://developers.lumos.com/reference/deleteaccesspolicy.md): Delete an access policy by ID. - [Reconnect App](https://developers.lumos.com/reference/reconnectapp.md): Update an app in place: apply domain-specific metadata overrides (the same fields as `PATCH /apps/{app_id}`) and/or rotate an integration's credentials. Providing `auth`/`settings`/`version` (with the matching `app_class_id`) reconnects the app: credentials are always overwritten and re-validated, and a sync is triggered — like connect, the app either connects in-band or awaits browser consent in the Lumos UI, and while a sync is in flight the request is throttled with `429` and a `Retry-After` header. Metadata-only bodies (custom apps, or integrations without credential changes) never touch credentials. - [Disconnect App](https://developers.lumos.com/reference/disconnectapp.md): Disconnect an API-managed app. For integrations this removes the stored credentials and returns the app to a connectable state; for custom apps it removes the app. In both cases, when no users remain the underlying record is also deleted where possible (a record still referenced by other Lumos data is kept, disconnected). Reconnect an integration later with `PUT /apps/{app_id}`. Returns 404 if `app_id` is unknown in the caller's organization. - [Trigger App Sync](https://developers.lumos.com/reference/triggerappsync.md): Trigger a sync for a connected app on demand (e.g. from automation, after Terraform has connected it). The sync runs asynchronously — the call returns `202 Accepted` once the sync is launched; poll `GET /apps/{app_id}` to follow status. Requires `sync_type` (only `full_sync` is supported today). The app must be connected or in an error state from a prior sync (so callers can retry after failure). Manual/CSV apps are not supported. Only one sync may run at a time: while a sync is in flight the request is rejected with `409` — wait for the running sync to finish, then retry. - [List Integrations](https://developers.lumos.com/reference/listintegrations.md): List the integrations (apps) available to connect in your domain (paginated). Only connectable integrations are returned — catalog-only apps (e.g. discovered SaaS without a Lumos integration) are excluded. Returns catalog metadata only — name, category, and logo. Integrations you have connected are read via the Apps API (`GET /apps`). - [Get Integration](https://developers.lumos.com/reference/getintegration.md): Get a connectable integration (app) by its `app_class_id` (e.g. `okta.com`). Returns catalog metadata only; integrations you have connected are read via the Apps API (`GET /apps`). - [Get Integration Connection Schema](https://developers.lumos.com/reference/getintegrationconnectionschema.md): Get the connection schema for an integration — the JSON schema of the `auth` and `settings` fields needed to connect it via `POST /apps`. Use it to discover how to connect an integration *before* connecting it (e.g. to populate a Terraform resource). `app_class_id` is the canonical identifier (e.g. `okta.com`, `slack_ics`) — the same value the connect body uses. Integrations whose connection schema Lumos cannot describe yet return 404. - [AppStore](https://developers.lumos.com/reference/appstore.md): The AppStore API lets you programmatically interact with objects in the AppStore. - [Get Appstore App](https://developers.lumos.com/reference/getappstoreapp-1.md): Get AppStore app. - [Get Appstore Apps](https://developers.lumos.com/reference/getappstoreapps-1.md): List all AppStore apps. - [Add App To Appstore](https://developers.lumos.com/reference/addapptoappstore-1.md): Add app to AppStore with given settings. - [Remove App From Appstore](https://developers.lumos.com/reference/removeappfromappstore-1.md): Remove app from AppStore. - [Get Appstore App Settings](https://developers.lumos.com/reference/getappsettings-1.md): Get App settings. - [Get Appstore App Settings](https://developers.lumos.com/reference/getappstoreappsettings-1.md): Get AppStore app settings. - [Update Domain App Appstore Settings](https://developers.lumos.com/reference/updateappsettings-1.md): Update app settings. - [Update Appstore App Settings](https://developers.lumos.com/reference/updateappstoreappsettings-1.md): Update AppStore app settings. - [Get Appstore Permission](https://developers.lumos.com/reference/get_appstore_permission_appstore_requestable_permissions__permission_id__get-1.md): Get an AppStore permission. - [Get Appstore Permissions For App](https://developers.lumos.com/reference/get_appstore_permissions_for_app_appstore_apps__app_id__requestable_permissions_get-1.md): Get AppStore permissions for an application. - [Get Appstore Permissions](https://developers.lumos.com/reference/get_appstore_permissions_appstore_requestable_permissions_get-1.md): Get AppStore permissions for an application. - [Create Appstore Requestable Permission](https://developers.lumos.com/reference/create_appstore_requestable_permission_appstore_requestable_permissions_post-1.md): **Create a permission attached to an App in the AppStore.** *Required fields:* - app-identifier. The App should be identified either by app_id or app_class_id + app_instance_id. - label *Defaults:* - request_config: - appstore_visibility: HIDDEN - allowed_groups: - type: ALL_GROUPS - groups: [] - request_approval_config - manager_approval: NONE - request_approval_stages: [] - request_fulfillment_config - manual_steps_needed: false - All other fields will have null values by default. - [Update Appstore Permission](https://developers.lumos.com/reference/update_appstore_permission_appstore_requestable_permissions__permission_id__patch-1.md): **Update an AppStore permission.** All fields present in the payload will override the permission's data. Any missing fields will be disregarded. Non-updatable fields for now: request_config -> request_fulfillment_config -> provisioning_group - [Delete Appstore Permission](https://developers.lumos.com/reference/delete_appstore_permission_appstore_requestable_permissions__permission_id__delete-1.md): Delete a requestable permission by ID. Only permissions of type 'NATIVE' can be deleted. - [Get Appstore Pre Approval Rule](https://developers.lumos.com/reference/get_appstore_pre_approval_rule_appstore_pre_approval_rules__pre_approval_rule_id__get-1.md): Get an AppStore pre-approval rule. - [Get Appstore Pre Approval Rules For App](https://developers.lumos.com/reference/get_appstore_pre_approval_rules_for_app_appstore_pre_approval_rules_get-1.md): Get AppStore pre-approval rules for an app. - [Create Pre Approval Rule](https://developers.lumos.com/reference/create_pre_approval_rule_appstore_pre_approval_rules_post-1.md): Create a pre-approval rule attached to an App in the AppStore. - [Update Pre Approval Rule](https://developers.lumos.com/reference/update_pre_approval_rule_appstore_pre_approval_rules__pre_approval_rule_id__patch-1.md): **Update a pre-approval rule attached to an App in the AppStore.** All fields present in the payload will override the pre-approval rule's data. Any missing fields will be disregarded. - [Delete Pre Approval Rule](https://developers.lumos.com/reference/delete_pre_approval_rule_appstore_pre_approval_rules__pre_approval_rule_id__delete-1.md): Delete a pre-approval rule by ID. - [Get Access Request](https://developers.lumos.com/reference/getaccessrequest-1.md): Get access request by ID. - [Get Access Requests](https://developers.lumos.com/reference/getaccessrequests-1.md): Get all access requests for the current organization. - [Create Access Request](https://developers.lumos.com/reference/createaccessrequest-1.md): Create a request to access a specific permission in the appstore. - [Cancel Access Request](https://developers.lumos.com/reference/cancelaccessrequest-1.md): Cancel an access request. - [Create User Offboarding](https://developers.lumos.com/reference/createuseroffboarding.md): Trigger or schedule an offboarding for an identity using the domain's configured offboarding workflow. Omit `scheduled_at` to run immediately, or provide a future datetime to schedule it. - [Get User Offboarding](https://developers.lumos.com/reference/getuseroffboarding.md): Get a user offboarding by ID. - [Cancel User Offboarding](https://developers.lumos.com/reference/canceluseroffboarding.md): Cancel a scheduled or in-progress user offboarding. - [Get Art](https://developers.lumos.com/reference/lumos-art-1.md): Return Lumos ASCII art. Can be used to verify the API is working. - [Get Info](https://developers.lumos.com/reference/lumos-liveness-check-1.md): Returns current git revision. - [Get Current User](https://developers.lumos.com/reference/currentuser-1.md): Get current user - [🔌 Lumos Connector API](https://developers.lumos.com/reference/the-lumos-connector-api.md) - [📚 Overview](https://developers.lumos.com/reference/overview-of-custom-connectors.md) - [Authorization and Authentication](https://developers.lumos.com/reference/authorization-and-authentication.md): #### Learn how to use the SDK to build integrations with different authorization styles. - [Connector Capabilities](https://developers.lumos.com/reference/connector-capabilities.md): ## 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`](docs:connector-capabilities#validate-credentials) capability. Depending on the authentication method(s) that the app supports, this may include some [OAuth capabilities](connector-capabilities#oauth-capabilities). 2. After this, we suggest you implement [read capabilities](connector-capabilities#read-capabilities) to let Lumos sync the app data into Lumos. 3. Next,[write capabilities](connector-capabilities#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. - [Error Handling](https://developers.lumos.com/reference/error-handling.md): #### Proper error handling is crucial for creating robust and reliable connectors. Lumos provides both standard and custom error handling mechanisms to address various scenarios. - [Pagination](https://developers.lumos.com/reference/pagination.md): #### Learn how to use the pagination utilty in the SDK for efficient response handling - [SDK Utilities](https://developers.lumos.com/reference/sdk-utilities.md): #### An overview of the different ways Lumos helps make implementation steps easier - [Settings](https://developers.lumos.com/reference/settings.md): #### Learn how to configure the settings required to connect an integration - [/list-connector-app-ids](https://developers.lumos.com/reference/list_connector_app_ids.md): 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. - [/{connector_id}/info](https://developers.lumos.com/reference/info.md): 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. - [/{connector_id}/list_custom_attributes_schema](https://developers.lumos.com/reference/list_custom_attributes_schema.md): Retrieve the schema definition for all custom attributes supported by this connector. - [/{connector_id}/connected_info](https://developers.lumos.com/reference/get_connected_info.md): Gets the connected info of a connector given. This operation retrieves the connected info of a connector given the credentials and settings. This is only used if the connector has aspects of it's info response that change based on the credentials and settings. IMPORTANT: This only need to be implemented if the connector has elements of it's info response that are dependent on the credentials and settings. Examples: - A connector that only has the ability to suspend accounts if given a write capable api token - A connector that has resource types that can only be determined via an api call If not implemented, the static info response can be used. This endpoint should be called: - Any time you need an element of the info response and the connector implements this capability - [/{connector_id}/find_entitlement_associations](https://developers.lumos.com/reference/find_entitlement_associations.md): 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. - [/{connector_id}/get_last_activity](https://developers.lumos.com/reference/get_last_activity.md): 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 - [/{connector_id}/list_accounts](https://developers.lumos.com/reference/list_accounts.md): 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. - [/{connector_id}/list_entitlements](https://developers.lumos.com/reference/list_entitlements.md): 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 - [/{connector_id}/list_resources](https://developers.lumos.com/reference/list_resources.md): 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. - [/{connector_id}/validate_credentials](https://developers.lumos.com/reference/validate_credentials.md): 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 - [/{connector_id}/get_account](https://developers.lumos.com/reference/get_account.md): Retrieve detailed information about a single user account. This operation fetches information for a single account identified by its integration-specific user ID. It can be used to: - Display an individual user’s profile - Pull the most up-to-date custom attribute values for a user - [/{connector_id}/get_account_entitlement_associations](https://developers.lumos.com/reference/get_account_entitlement_associations.md): Find associations between entitlements and resources for a single account. 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. - [/{connector_id}/get_application](https://developers.lumos.com/reference/get_application.md): Retrieve a single application by its ID Common use cases include: - Getting detailed information about a specific application - Validating application existence and status - [/{connector_id}/get_application_account](https://developers.lumos.com/reference/get_application_account.md): Retrieves a single assignment for an account to an application. This will return a NOT_FOUND error if the assignment does not exist. This operation fetchs a single account assignment to an application. It can be used to: - Validate the assignment of a user to an application - Audit a user's application access - [/{connector_id}/get_data_recency](https://developers.lumos.com/reference/get_data_recency.md): Retrieve the recency information for data surfaced by standard capabilities. This operation enables connectors to indicate how "fresh" the data is that they surface through their standard capabilities. This is particularly important for connectors that source data from scheduled dumps, snapshots, or other non-real-time data sources. ## Use Cases - **Data Freshness Assessment**: Understand how current the data is from each capability - **Scheduled Data Sources**: Handle connectors that read from CSV files, database snapshots, or other periodically updated data sources - **Data Quality Monitoring**: Track data staleness for compliance and accuracy ## Capability Recency Mapping The response maps each standard capability to an optional datetime indicating when the data for that capability was last updated: - **Non-null datetime**: Indicates the data for this capability is current as of the specified timestamp - **null datetime**: Indicates the connector cannot determine or does not track recency for this capability ## Connector Implementation Connectors should implement this capability when: - They source data from scheduled dumps or snapshots - They can provide meaningful recency information Connectors that always provide "live" data may return null for all capabilities or omit this capability entirely. ## Data Reconciliation - [/{connector_id}/list_activity_records](https://developers.lumos.com/reference/list_activity_records.md): List activity records for a given connector within a time window. This is commonly used for audit use cases, such as: - Reviewing recent entitlement usage (e.g., licenses used in the last 90 days) - [/{connector_id}/list_applications](https://developers.lumos.com/reference/list_applications.md): Retrieve a list of applications associated with the given credentials Common use cases include: - Discovering applications managed by this integration - [/{connector_id}/list_applications_accounts](https://developers.lumos.com/reference/list_applications_accounts.md): Retrieve a list of account ids associated to assigned application ids Common use cases include: - Auditing connected accounts - Account discovery and synchronization - [/{connector_id}/list_applications_activity_records](https://developers.lumos.com/reference/list_applications_activity_records.md): List activity records for applications within a time window. This is commonly used for audit use cases, such as: - Reviewing recent entitlement usage (e.g., licenses used in the last 90 days) - [/{connector_id}/list_applications_entitlement_associations](https://developers.lumos.com/reference/list_applications_entitlement_associations.md): - Find associations between entitlements and resources in applications of an integration system. - - This operation retrieves the relationships between entitlements and their associated resources - in the applications managed by a 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. - - - [/{connector_id}/list_applications_entitlements](https://developers.lumos.com/reference/list_applications_entitlements.md): List all entitlements available in the applications of 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 - [/{connector_id}/list_applications_resources](https://developers.lumos.com/reference/list_applications_resources.md): List all resources available in the applications of 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. - [/{connector_id}/list_expenses](https://developers.lumos.com/reference/list_expenses.md): Retrieve a list of reimbursements and/or card transactions Common use cases include: - Tracking overall software spend - Identifying "rogue" employee spend - [/{connector_id}/list_updated_accounts](https://developers.lumos.com/reference/list_updated_accounts.md): 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 - [/{connector_id}/activate_account](https://developers.lumos.com/reference/activate_account.md): 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 - [/{connector_id}/assign_entitlement](https://developers.lumos.com/reference/assign_entitlement.md): 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 - [/{connector_id}/create_account](https://developers.lumos.com/reference/create_account.md): 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. - [/{connector_id}/deactivate_account](https://developers.lumos.com/reference/deactivate_account.md): 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. - [/{connector_id}/delete_account](https://developers.lumos.com/reference/delete_account.md): Delete an existing user account in an integration system. This is not a reversible operation and may result in data loss - [/{connector_id}/unassign_entitlement](https://developers.lumos.com/reference/unassign_entitlement.md): Unassign an Entitlement from a user account. Depends on the constraints (e.g. min, max) of this entitlement type. - [/{connector_id}/assign_application](https://developers.lumos.com/reference/assign_application.md): Assigns an application in the third-party system. Note: Only entitlements that are required for account assignment should be specified here. Optional entitlements should be assigned after assignment using the assign_entitlement operation. - [/{connector_id}/assign_application_entitlement](https://developers.lumos.com/reference/assign_application_entitlement.md): Assign an entitlement to an account within a managed application. 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 - [/{connector_id}/downgrade_license](https://developers.lumos.com/reference/downgrade_license.md): Downgrade a user's license to a lower tier. Essentially, this capability should "reset" a user account to exist without a license, and free-up the license for other user accounts. The mechanism of downgrading a license is connector/service-specific. - [/{connector_id}/release_resources](https://developers.lumos.com/reference/release_resources.md): Removes all resources associated with a user account. Intended to "free-up" a user account. - [/{connector_id}/transfer_data](https://developers.lumos.com/reference/transfer_data.md): Transfer data from one account to another. Any data that is transferrable between accounts should be handled by this capability. This capability is intended to be used in the One-Click Offboarding Flow. What is and what isn't transferred is connector/service-specific. - [/{connector_id}/unassign_application](https://developers.lumos.com/reference/unassign_application.md): Unassigns an account from an application in an integration system. - [/{connector_id}/unassign_application_entitlement](https://developers.lumos.com/reference/unassign_application_entitlement.md): Unassign an Entitlement from a user account. Depends on the constraints (e.g. min, max) of this entitlement type. - [/{connector_id}/update_account](https://developers.lumos.com/reference/update_account.md): Update an existing user account in the third-party system. This operation updates an existing user account with the specified ID. Connectors are expected to extend the type UpdateableAccount and use it as both the request payload and the response payload. E.g. if the specific app requires email, that should be exposed as an optional string when updating, and a required string when returning the result. - [/{connector_id}/get_authorization_url](https://developers.lumos.com/reference/get_authorization_url.md): 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. - [/{connector_id}/handle_authorization_callback](https://developers.lumos.com/reference/handle_authorization_callback.md): Handle Authorization Callback This operation processes the OAuth callback to exchange the authorization code for access and refresh tokens. - [/{connector_id}/handle_client_credentials_request](https://developers.lumos.com/reference/handle_client_credentials_request.md): 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". - [/{connector_id}/refresh_access_token](https://developers.lumos.com/reference/refresh_access_token.md): 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. - [/{connector_id}/app_info](https://developers.lumos.com/reference/app_info.md): Info capability that can be mutated based on its input, eg. the apps authentication parameters and settings. Returns basic information and the OAS specification of the particular app. This operation is currently used in: - http-server /docs and /redoc endpoints - CI/CD actions like OASDiff In the future, this can be used for: - Connected info - Schema validation, type safety, etc. - In place of the static info - [Lumos Terraform Provider](https://developers.lumos.com/reference/lumos-terraform-provider.md) - [Inline Webhooks](https://developers.lumos.com/reference/access-request-webhooks.md): Our webhooks let you execute custom scripts before, during, or after an access request in Lumos. Your scripts can be hosted on an iPaaS tool like Okta Workflows, or through a serverless function such as AWS Lambdas. - [Lumos CLI](https://developers.lumos.com/reference/lumos-cli.md): Learn more about the Lumos Command Line Interface. - [Lumos CLI Commands](https://developers.lumos.com/reference/lumos-cli-commands.md): Overview of available commands on the CLI. ## Recipes - [Create new permissions with a provisioning group](https://developers.lumos.com/recipes/create-new-permissions-with-a-provisioning-group.md) - [Find a Group by Name](https://developers.lumos.com/recipes/find-a-group-by-name.md) - [List all your company's apps](https://developers.lumos.com/recipes/list-all-your-companys-apps.md) - [List Inactive AppStore Approver or Admins](https://developers.lumos.com/recipes/list-inactive-appstore-approver-or-admins.md) - [Upload Activity Records to Lumos](https://developers.lumos.com/recipes/upload-activity-records-to-lumos.md) ## Pages - [Public Roadmap](https://developers.lumos.com/page/public-roadmap.md)