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. |
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 |
Required SAML assertion fields
Cotool identifies users by email address. Configure the IdP to send the user’s work email as one of:
NameIDemailhttp://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 |
- 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 |
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. |
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. |
PATCH support
Cotool supports SCIM add and replace operations for these paths:
activeuserNameexternalIdnameemails
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 |
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 |
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. |
