> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attention.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM Provisioning (Okta)

> Automatically create, update, and deactivate Attention users and teams from Okta using SCIM 2.0.

Attention supports [SCIM 2.0](https://datatracker.ietf.org/doc/html/rfc7644) so your identity provider can manage Attention users and teams automatically. Assign someone to the Attention app in Okta and their account is created; unassign them and it is deactivated.

<Info>
  **SCIM is provisioning, not login.** SCIM creates and updates accounts. Signing in is configured separately — see [Single Sign-On](/workspace-setup/single-sign-on). Most organizations enable both: SSO for authentication, SCIM so users exist before they authenticate.
</Info>

## How Attention maps to SCIM

| SCIM resource   | Attention object                           |
| --------------- | ------------------------------------------ |
| User            | User                                       |
| Group           | [Team](/workspace-setup/teams-roles-seats) |
| `active: false` | Deactivated user (reversible)              |

Group membership becomes team membership. Roles are assigned through a custom attribute described below.

## Before you start

* **Admin** role in Attention
* An **organization-level** API key
* Okta Super Admin or Application Admin access

## Step 1: Create an organization-level API key

Follow [API Authentication](/api-authentication) to create a key from **Settings → API Keys**.

<Warning>
  The key must be an **organization-level** key, created by an Admin. A personal API key is rejected on every SCIM request with `403 Organization not found for API key`. If your test connection fails with a 403, this is almost always the reason.
</Warning>

Verify the key works before touching Okta:

```bash theme={null}
curl -i https://api.attention.tech/scim/v2/ServiceProviderConfig \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A `200 OK` with a JSON body means the key is valid and correctly scoped.

## Step 2: Configure the SCIM connector in Okta

In your Attention app in Okta, go to **Provisioning → Configure API Integration** and enable API integration.

| Field                             | Value                                             |
| --------------------------------- | ------------------------------------------------- |
| SCIM connector base URL           | `https://api.attention.tech/scim/v2`              |
| Unique identifier field for users | `userName`                                        |
| Supported provisioning actions    | Push New Users, Push Profile Updates, Push Groups |
| Authentication Mode               | HTTP Header                                       |
| Authorization                     | `Bearer YOUR_API_KEY`                             |

<Warning>
  **Unique identifier field must be `userName`.** Attention only supports filtering users by `userName` and `active`. If this field is set to anything else (`email`, `externalId`, `id`), the lookup filter is ignored rather than rejected, Okta receives your entire user list, and it may match the wrong person — silently applying updates to the wrong account.
</Warning>

Click **Test Connector Configuration** to confirm the connection.

<Note>
  EU-hosted organizations use `https://api.eu-a.attention.tech/scim/v2`. If you are unsure which applies, ask your Attention point of contact.
</Note>

## Step 3: Enable provisioning to Attention

Under **Provisioning → To App → Edit**, enable:

* **Create Users**
* **Update User Attributes**
* **Deactivate Users**

Deactivation is reversible: re-assigning a user in Okta restores the account with its history intact.

## Step 4: Map user attributes

<Steps>
  <Step title="Required attributes">
    | Okta attribute   | SCIM attribute    |
    | ---------------- | ----------------- |
    | `user.email`     | `userName`        |
    | `user.firstName` | `name.givenName`  |
    | `user.lastName`  | `name.familyName` |

    `userName` must be the user's email address — Attention matches users by email.
  </Step>

  <Step title="Optional attributes">
    `displayName`, `emails`, `locale`, `timezone`, and `preferredLanguage` are accepted and stored where they have an Attention equivalent.
  </Step>
</Steps>

## Step 5: Assign roles (optional)

Roles are set through an Okta-specific extension attribute rather than the standard SCIM `roles` field.

<Steps>
  <Step title="Get your role UUIDs">
    Call the roles endpoint with your API key:

    ```bash theme={null}
    curl https://api.attention.tech/v2/organizations/roles \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Add a custom attribute in Okta">
    In the Okta **Profile Editor** for the Attention app, add a string attribute:

    * **External namespace:** `urn:okta:onprem_app:1.0:user:custom`
    * **External name:** `roleUUID`
  </Step>

  <Step title="Map it">
    Map the attribute to the role UUID you want each user to receive — a constant value, or an expression driven by Okta group membership.
  </Step>
</Steps>

The resulting request looks like this:

```json theme={null}
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:okta:onprem_app:1.0:user:custom"
  ],
  "userName": "jane.smith@company.com",
  "name": { "givenName": "Jane", "familyName": "Smith" },
  "active": true,
  "urn:okta:onprem_app:1.0:user:custom": {
    "roleUUID": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

<Note>
  A user holds **one role per organization**. Sending `roleUUID` replaces any role the user currently has, including one set manually in Attention. The role must belong to your organization or the request fails with `400`.
</Note>

<Warning>
  The standard SCIM `roles` array is **not supported**. A payload containing `roles` succeeds but assigns no role — it fails silently. Use the custom extension above.
</Warning>

## Step 6: Push groups as teams

Open the **Push Groups** tab and push the Okta groups that should exist as Attention teams. Each pushed group becomes a team, and its members become team members.

Push users before groups. Okta creates users first and then reconciles group membership, which is the order Attention expects.

## Provisioning behavior

<AccordionGroup>
  <Accordion title="Users created without a group">
    A user provisioned before any group is pushed is placed in your organization's **Default** team, created automatically on first use. Once Push Groups runs, they gain their real team memberships and keep the Default membership until it is removed.
  </Accordion>

  <Accordion title="Seat type">
    Provisioned users receive a **Recording seat** — the Attention bot can join and record their meetings. To change someone to a Listener seat, edit the user in Attention; see [Teams, Roles & Seats](/workspace-setup/teams-roles-seats).
  </Accordion>

  <Accordion title="Deactivating a user">
    Unassigning a user in Okta sends `active: false`, which deactivates the account without destroying data. Re-assigning restores it. `DELETE /Users/{id}` behaves the same way — it deactivates rather than erases.
  </Accordion>

  <Accordion title="Deleting a group">
    Deleting or unpushing a group archives the Attention team and hides it from group listings, but **does not remove its members**. Those users remain active in Attention.

    Deleting a group is not an offboarding action. To offboard people, deactivate each user.
  </Accordion>

  <Accordion title="Users who were already invited">
    If someone was invited through Attention and is later provisioned via SCIM, the pending invitation is linked to the new account and its role is applied, unless the SCIM request specifies a role of its own.
  </Accordion>

  <Accordion title="Repeated or retried requests">
    Creating a user who already exists returns the existing account rather than an error, so Okta retries are safe. Re-adding a user who is already a team member is likewise harmless.
  </Accordion>
</AccordionGroup>

## Limitations

* **Filtering** — only `userName eq` and `active eq` are supported, combined with `and`. Operators such as `ne`, `co`, `sw`, `gt`, and `lt` are not supported, and unsupported filters are ignored rather than rejected.
* **Page size** — listings return at most 100 resources per request. Use `startIndex` and `count` to page.
* **`roles` attribute** — not supported; use the custom extension in Step 5.
* **`externalId`** — accepted but not stored, and not returned as sent. Do not rely on it as a correlation key.
* **Group membership via `PUT /Users/{id}`** — ignored. Change membership through the Groups endpoint, or with `PATCH /Users/{id}` using `add` or `remove` on `groups`.
* **`/Me`** — not implemented.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The `Authorization` header is missing or the key is invalid. Confirm the header is `Bearer YOUR_API_KEY` and that the key has not been deleted.
  </Accordion>

  <Accordion title="403 Organization not found for API key">
    The key is a personal key, not an organization-level one. Have an Admin create an organization-level key and update Okta. See Step 1.
  </Accordion>

  <Accordion title="400 team ... not found in organization">
    A pushed group references a team that does not exist in your organization. Re-push the group so Attention creates it, then retry the user.
  </Accordion>

  <Accordion title="400 user ... already exists in a different organization">
    The email address already belongs to a user in another Attention organization. Contact support — this cannot be resolved from Okta.
  </Accordion>

  <Accordion title="404 Not Found on a user or group">
    The resource does not exist in your organization, or it belongs to another one. Confirm you are using the ID Attention returned when the resource was created.
  </Accordion>

  <Accordion title="Duplicate key errors when adding members">
    Harmless — the user is already a member of the team. It usually means Okta retried or ran overlapping sync jobs.
  </Accordion>
</AccordionGroup>

Okta records every request under **Reports → System Log** (filter on your Attention app), which is the fastest place to see the exact payload and response.

## Next steps

<CardGroup cols={2}>
  <Card title="Single Sign-On" icon="key" href="/workspace-setup/single-sign-on">
    Configure Okta, Google, or EntraID authentication
  </Card>

  <Card title="Teams, Roles & Seats" icon="user-group" href="/workspace-setup/teams-roles-seats">
    Understand what roles and seat types grant
  </Card>
</CardGroup>

<Info>
  Need help with SCIM provisioning? Contact [support@attention.com](mailto:support@attention.com) or your Attention account manager.
</Info>