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

# Connecting SCIM Apps with Lumos

Bring any application that follows the SCIM 2.0 specification into Lumos, even when a dedicated connector for that application doesn't exist. The connector implements the SCIM 2.0 Protocol (RFC 7644) and Core Schema (RFC 7643), and syncs and provisions users and group membership.

Lumos offers two authentication methods for SCIM. Pick the one your SCIM provider supports:

* **SCIM Token**: a static token, sent as a Bearer token on every request. Use the **SCIM Connector** card.
* **OAuth 2.0 Client Credentials**: for providers that issue tokens through an OAuth client instead. Use the **SCIM Connector (OAuth Client Credentials)** card. The steps are the same except for the credential fields, which each step below names.

## Requirements

* **Application requirement:** the application's API must follow the **SCIM 2.0** specification. SCIM 1.1 is not supported.
* **Authentication:** a SCIM token generated in your SCIM provider. For the OAuth method, a **Client ID** and **Client Secret** from an OAuth 2.0 application that uses the Client Credentials grant type, plus the **Token URL** (the OAuth endpoint that issues access tokens).
* **Connection fields:** the token, an **App Instance Identifier**, and the **Base URL** of your SCIM API, typically `https://{domain}/scim/v2`.
* **Permission scoping:** provisioning requires **write** access to Users and Groups on the SCIM API. A sync-only connection needs read access only.

## Read-only or provisioning

Access level follows entirely from the token's permissions in your SCIM provider. There is no separate read-only tile. A token scoped to read access on Users and Groups provides sync-only. Adding write access enables provisioning: creating, updating, and deleting users, and managing group membership.

> **Scoping a token down after connecting**
>
> If you reduce the token's permissions on an existing connection, provisioning operations start failing with 403 errors until the permissions are restored.

## 1. Prepare the application

1. Confirm the application exposes a SCIM 2.0 API and note its **Base URL**.
2. Generate a **SCIM token** in your SCIM provider and copy it. For the OAuth method, create an OAuth 2.0 application with the Client Credentials grant type instead, and copy its **Client ID**, **Client Secret**, and **Token URL**. Consult the provider's documentation for the specific steps.
3. Confirm the token (or OAuth application) has read access to the Users and Groups endpoints, plus write access if you want provisioning.
4. If the application restricts API access by IP, allowlist the IP addresses listed in [Lumos IP addresses](/kb/ui-ux/general-lumos-settings/lumos-ip-addresses).

## 2. Connect in Lumos

1. Go to [Integrations](https://app.lumosidentity.com/integrations?tab=can_integrate) and click the **SCIM Connector** card, or the **SCIM Connector (OAuth Client Credentials)** card for the OAuth method. To reconnect an existing connection, use the [connected integrations](https://app.lumosidentity.com/integrations?tab=connected) tab.
2. Provide the **Token**, the **App Instance Identifier**, and the **Base URL**. For the OAuth method, provide the **Client ID**, **Client Secret**, and **Token URL** in place of the token.
3. Modify the endpoint paths only if the application doesn't use the default `/Users` and `/Groups` endpoints.
4. Click **Connect**.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users | Account | Yes | Yes | User accounts |
| Groups | Permission | Yes | Yes | Group membership. Provisioning adds and removes members; Lumos doesn't create groups. |

| **Deprovisioning Action** | **Type** | **Description** |
| :- | :- | :- |
| Deactivate | User | Sets the user's `active` attribute to false (`PATCH /Users/{id}`) |
| Delete | User | Permanently deletes the user (`DELETE /Users/{id}`) |
| Remove from group | Group membership | Removes the user from the group's members (`PATCH /Groups/{id}`) |

Which of Deactivate or Delete Lumos calls depends on the deprovisioning action configured for the app.

## API endpoints used

All requests carry the token (or, for the OAuth method, the access token issued by your Token URL) as a Bearer token in the `Authorization` header, against your configured Base URL.

| Endpoint | Method | Purpose |
| :- | :- | :- |
| `/Users` | GET | List all users (with pagination) |
| `/Users` | POST | Create a new user account |
| `/Users/{id}` | GET | Retrieve a specific user |
| `/Users/{id}` | PATCH | Update attributes or modify active status |
| `/Users/{id}` | DELETE | Permanently delete a user account |
| `/Groups` | GET | List all groups (with pagination) |
| `/Groups/{id}` | PATCH | Add or remove group members |
| `/ResourceTypes` | GET | Discover supported resource types |
| `/Schemas/{schema}` | GET | Retrieve schema definitions for custom attributes |
| `/ServiceProviderConfig` | GET | Get service provider capabilities |

For the request and response payloads Lumos sends on each lifecycle operation, see [SCIM Payload Examples](/integrations/generics/scim/examples).

## Troubleshooting

**Connection Failed.** Usually an unreachable endpoint. Verify the Base URL format (`https://{domain}/scim/v2`), test that the HTTPS endpoint is accessible, confirm the SSL certificate is valid, check firewall and security-group rules, and confirm DNS resolution works.

**401 Unauthorized.** The token, or the service account behind it, is invalid, expired, disabled, or locked. Verify the token, confirm the service account is active, and regenerate the token if needed.

**403 Forbidden.** The token lacks permissions on the SCIM API. Grant read permissions to Users and Groups, add the [Lumos IP addresses](/kb/ui-ux/general-lumos-settings/lumos-ip-addresses) to the allowlist, verify SCIM API access is enabled, and check application-level permission settings.

**404 Not Found.** Wrong path or SCIM not enabled. Verify the Base URL ends with `/scim/v2`, confirm SCIM is enabled in the application, check the application's docs for the correct endpoint path, and ensure the application supports SCIM 2.0, not 1.1.

**Users not syncing.** Verify `/Users` returns data, check users have `userName` and `emails` attributes, confirm the `active` attribute is set, review that responses match RFC 7644, and check pagination.

**Groups not syncing.** Verify `/Groups` is accessible, confirm groups have a `displayName`, and check the `members` array is properly formatted with valid user references.

**Provisioning operations failing.** Confirm the token has write permissions, verify required attributes are being sent, check the server supports the operation (POST, PATCH, DELETE), review `/ServiceProviderConfig` for supported operations, and verify `userName` uniqueness.