> ## 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.

# The Integration object

> The catalog of services Lumos can connect to, and how to see which credentials each one needs before you connect it.

An integration is a service Lumos knows how to connect to. An [app](https://docs.lumos.com/reference/v1/objects/app.md) is
one connected instance of an integration in your organization. `okta.com` is an integration. When
your organization connects Okta, the result is an app.

You read the two through different endpoints. Browse integrations to see what you could connect
and what credentials each one needs. Read apps to see what you have connected. Integrations carry
only catalog metadata. They hold nothing specific to your organization.

```json The Integration object theme={null}
{
  "app_class_id": "okta.com",
  "name": "Okta",
  "description": "Identity provider and single sign-on.",
  "category": "IT & Security",
  "logo_url": "https://logos.lumos.com/okta.png"
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `app_class_id` | string | Canonical identifier, such as `okta.com` or `slack_ics`. This is the value you pass when connecting. |
| `name` | string | Display name of the integration. |
| `description` | string or null | Short description of what the integration is. |
| `category` | string or null | Category, such as `IT & Security`. |
| `logo_url` | string or null | URL of the integration's logo. |

`app_class_id` is the only field you need to look up or connect an integration. It's the catalog's
identifier, the path parameter on the two lookup endpoints, and the `app_class_id` you send
to [Create App](https://docs.lumos.com/api-reference/v1/apps/create-app.md) to connect it.

## Which integrations are listed

This catalog is narrower than the catalog in the Lumos UI.
[List Integrations](https://docs.lumos.com/api-reference/v1/integrations/list-integrations.md) excludes SaaS products
that Lumos discovers but has no integration for, because you can't do anything with them through
this API. A missing service is one Lumos can't connect to through the API.

## Connection schema

Read an integration's connection schema before you connect it.
[Get Integration Connection Schema](https://docs.lumos.com/api-reference/v1/integrations/get-integration-connection-schema.md)
returns the JSON Schema of the `auth` and `settings` objects that
[Create App](https://docs.lumos.com/api-reference/v1/apps/create-app.md) expects when it connects an integration. With it,
you can write one connect flow instead of one per integration.

```bash theme={null}
curl -s 'https://api.lumos.com/v1/integrations/okta.com/connection-schema' \
  --header 'Authorization: Bearer lsk_your_token'
```

| Field | Description |
| - | - |
| `app_class_id` | Echoes the integration you asked about. |
| `auth_schema` | Draft-07 JSON Schema of the secret credentials, with no `$schema` key. Secret fields are marked `writeOnly`. |
| `settings_schema` | JSON Schema of the non-secret configuration: tenant URLs, routing, instance identifiers. |

Check these four points before you build a connect request:

* **The shape depends on the integration.** Most schemas are a flat object with credential keys at
  the top level. Integrations that support several authentication methods nest credentials under
  named groups, and your connect request must use the same nesting.
* **An empty `auth_schema`**, `{"type":"object","properties":{}}`, doesn't mean the integration
  needs no credentials. It means you don't send credentials in the request, and
  `auth_schema.description` says why. Usually you finish the connection through browser consent in
  the Lumos UI, which you can't do end to end through the API. For a few integrations, Lumos
  supplies the credential itself, and you connect with `settings` alone.
* **Instance identifiers go in `settings`, never in `auth`.** Some integrations require
  `app_instance_identifier` there, such as an Okta domain. Others derive it from the credentials
  while connecting. On-prem integrations take `on_prem_agent_cluster_id` in the same place.
* **A `404` can happen for a listed integration.** It means Lumos can't describe that
  integration's connection schema right now. For an on-prem integration, `detail` says what to do:
  connect an on-prem agent that runs the connector, or install the connector on one, then retry.
  For any other integration, connect it in the Lumos UI instead.

## Endpoints

| Endpoint | Path |
| - | - |
| [List Integrations](https://docs.lumos.com/api-reference/v1/integrations/list-integrations.md) | `GET /v1/integrations` |
| [Get Integration](https://docs.lumos.com/api-reference/v1/integrations/get-integration.md) | `GET /v1/integrations/{app_class_id}` |
| [Get Integration Connection Schema](https://docs.lumos.com/api-reference/v1/integrations/get-integration-connection-schema.md) | `GET /v1/integrations/{app_class_id}/connection-schema` |