> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # SAML and SCIM IdP setup > Public endpoint reference for configuring Cotool in identity providers such as Okta Use this page when configuring Cotool as a first-class application in an identity provider (IdP), such as Okta, Microsoft Entra ID, Google Workspace, OneLogin, or Ping Identity. Cotool uses **SAML 2.0** for single sign-on and **SCIM 2.0** for user provisioning. A Cotool admin can find the organization-specific values and generate SCIM tokens from [Authentication Settings](https://app.cotool.ai/settings/saml). All examples use Cotool Cloud at `https://app.cotool.ai`. ## SAML SSO Cotool is the SAML service provider (SP). Your IdP is the identity provider. | Field | Value | | ---------------------------- | ------------------------------------------------------------------------------------ | | SAML version | `2.0` | | ACS URL / Single sign-on URL | `https://app.cotool.ai/api/auth/saml/{orgId}/callback` | | SP Entity ID / Audience URI | The Entity ID shown in Cotool. By default, this is the ACS URL. | | Recipient / Destination | Same as the ACS URL. | | Default RelayState | Leave blank unless you are sending users to a specific Cotool path. | | SSO initiation | SP-initiated SSO is supported. IdP-initiated SSO can post assertions to the ACS URL. | | SAML response binding | HTTP POST to the ACS URL. | | Single logout | Not currently supported. | ### Login URLs Use either of these SP-initiated login URLs: | Purpose | URL | | ------------------------- | ------------------------------------------------------------------ | | Email discovery login | `https://app.cotool.ai/api/auth/saml/login?email=user@example.com` | | Organization-scoped login | `https://app.cotool.ai/api/auth/saml/{orgId}/login` | The email discovery URL resolves the Cotool organization from the configured SAML email domain, then starts the SAML flow. ### Required SAML assertion fields Cotool identifies users by email address. Configure the IdP to send the user's work email as one of: * `NameID` * `email` * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` Recommended IdP settings: | Setting | Recommended value | | -------------------- | -------------------------------------- | | Name ID format | `EmailAddress` | | Application username | Email address | | Assertion signing | Enabled | | Response signing | Enabled if required by your IdP policy | | Encryption | Not required | Cotool validates SAML assertions with the IdP signing certificate from the metadata XML configured in Cotool. ### Cotool admin setup 1. Open [Authentication Settings](https://app.cotool.ai/settings/saml). 2. Enable **SAML Single Sign-On**. 3. Enter the email domain used for login discovery, such as `example.com`. 4. Copy the Cotool **ACS URL** and **Entity ID** into your IdP application. 5. Paste your IdP metadata XML into Cotool, or fetch it from your IdP metadata URL. 6. Save the settings and test SP-initiated login. ## SCIM provisioning Cotool implements SCIM 2.0 user provisioning with bearer-token authentication. | Field | Value | | --------------- | ------------------------------------------------- | | SCIM version | `2.0` | | SCIM base URL | `https://app.cotool.ai/api/scim/v2/{orgId}` | | Users endpoint | `https://app.cotool.ai/api/scim/v2/{orgId}/Users` | | Authentication | `Authorization: Bearer {scimToken}` | | Groups | Not currently supported | | Password sync | Not supported | | Bulk operations | Not supported | Generate or rotate the SCIM bearer token in [Authentication Settings](https://app.cotool.ai/settings/saml). Cotool shows the token only once, so copy it into the IdP when it is generated. ### Supported SCIM endpoints | Method | Endpoint | Purpose | | -------- | ------------------------ | --------------------------------------------------------------------------- | | `GET` | `/ServiceProviderConfig` | Return SCIM capability metadata. | | `GET` | `/Users` | List users with pagination and optional filters. | | `POST` | `/Users` | Create a user, or update an existing user matched by email or `externalId`. | | `GET` | `/Users/{userId}` | Fetch a user by Cotool user ID. | | `PUT` | `/Users/{userId}` | Replace supported user fields. | | `PATCH` | `/Users/{userId}` | Update supported user fields. | | `DELETE` | `/Users/{userId}` | Deactivate the user by setting `active` to `false`. | ### Supported user attributes Cotool accepts and returns these SCIM user fields: | Attribute | Notes | | ----------------- | ---------------------------------------------------------------------------- | | `schemas` | Optional on input. Responses include the SCIM core User schema. | | `id` | Cotool user ID. Returned by Cotool. | | `externalId` | Stored and used for matching provisioned users. | | `userName` | Required unless `emails[0].value` is present. Must be a valid email address. | | `name.givenName` | Optional. | | `name.familyName` | Optional. | | `name.formatted` | Optional. | | `emails[].value` | Optional when `userName` is present. The primary or first email is used. | | `active` | `false` deactivates the user. | New SCIM-created users receive the default role selected in Cotool's SCIM settings. ### Filtering and pagination `GET /Users` supports: | Query parameter | Support | | --------------- | --------------------------------------------------------------------------------------------------- | | `filter` | `userName eq "user@example.com"`, `emails.value eq "user@example.com"`, or `externalId eq "abc123"` | | `startIndex` | 1-based index. Defaults to `1`. | | `count` | Defaults to `100`. Maximum `200`. | Sorting is not currently supported. ### PATCH support Cotool supports SCIM `add` and `replace` operations for these paths: * `active` * `userName` * `externalId` * `name` * `emails` `remove` operations are not currently supported. ## Okta configuration notes ### SAML application In Okta, create a SAML 2.0 application and use: | Okta field | Cotool value | | --------------------------- | ---------------- | | Single sign-on URL | Cotool ACS URL | | Recipient URL | Cotool ACS URL | | Destination URL | Cotool ACS URL | | Audience URI (SP Entity ID) | Cotool Entity ID | | Name ID format | `EmailAddress` | | Application username | Email | After creating the app, copy Okta's IdP metadata XML or metadata URL into Cotool. ### SCIM provisioning Enable SCIM provisioning for the Okta application and use: | Okta field | Cotool value | | --------------------------------- | ------------------------------------------------------ | | SCIM connector base URL | Cotool SCIM base URL | | Unique identifier field for users | `userName` | | Supported provisioning actions | Create users, update user attributes, deactivate users | | Authentication mode | HTTP Header / Bearer token | | Bearer token | Token generated in Cotool | Use Okta's **Test Connector Configuration** action after saving the SCIM base URL and bearer token. ## Troubleshooting | Symptom | Check | | ---------------------------------------- | ------------------------------------------------------------------------------------------- | | SAML login cannot find the organization | Confirm the user's email domain matches the domain configured in Cotool. | | SAML assertion is rejected | Confirm the IdP metadata XML in Cotool contains the active signing certificate and SSO URL. | | User signs in but lands on an error page | Confirm the assertion includes the user's email as `NameID` or a supported email attribute. | | SCIM returns `401` | Rotate the SCIM token in Cotool and update the IdP. | | SCIM returns `403` | Confirm SCIM is enabled in Cotool for the organization. | | SCIM returns `409` | Confirm the email address or `externalId` is not already assigned to another user. |