SAML and SCIM IdP setup

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.

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.

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

Open Authentication Settings.
Enable SAML Single Sign-On.
Enter the email domain used for login discovery, such as example.com.
Copy the Cotool ACS URL and Entity ID into your IdP application.
Paste your IdP metadata XML into Cotool, or fetch it from your IdP metadata URL.
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. 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.

Getting Started

Core Concepts

Chat

Agents

Triage

Detections

Improving Agents

Settings

Integrations

SAML SSO

Required SAML assertion fields

Cotool admin setup

SCIM provisioning

Supported SCIM endpoints

Supported user attributes

PATCH support

Okta configuration notes

SAML application

SCIM provisioning

Troubleshooting

​SAML SSO

​Login URLs

​Required SAML assertion fields

​Cotool admin setup

​SCIM provisioning

​Supported SCIM endpoints

​Supported user attributes

​Filtering and pagination

​PATCH support

​Okta configuration notes

​SAML application

​SCIM provisioning

​Troubleshooting

SAML SSO

Login URLs

Required SAML assertion fields

Cotool admin setup

SCIM provisioning

Supported SCIM endpoints

Supported user attributes

Filtering and pagination

PATCH support

Okta configuration notes

SAML application

SCIM provisioning

Troubleshooting