Skip to main content
API docs by Redocly

Retool SCIM 2.0 API (1.0.0)

Download OpenAPI specification:Download

Retool implements a subset of the SCIM 2.0 REST API that is required to work with IDP vendors like Okta. If required, it's also possible to use these APIs directly to have your own custom user and role management system.

Base URL

All SCIM API endpoints are available at /api/scim/v2/. The full base URL includes the URL for your Retool cloud or self-hosted instance, such as https://retool.example.com/api/scim/v2/. To perform actions on a child Space, use its domain, e.g., https://retool-docs-space.example.com/, instead of the admin Space domain.

Authentication

The SCIM 2.0 API uses Bearer (token) authentication. You must provide your Retool API token with all API requests. See the SCIM user provisioning guide to learn how to create an access token.

Pagination

The SCIM 2.0 API does not support pagination. Parameters such as count and startIndex are ignored.

Groups

SCIM user groups.

List groups

Retrieve a list of all SCIM groups.

Responses

Request samples 

curl -X GET "https://retool.example.com:3000/api/scim/v2/Groups" \
-H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"

Response samples

Content type
application/json
{
  • "totalResults": 25,
  • "itemsPerPage": 1,
  • "startIndex": 0,
  • "schemas": [
    ],
  • "Resources": [
    ]
}

Create a group

Create a new SCIM group.

Request Body schema: application/json
required
displayName
required
string

The display name of the group.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "displayName": "employees",
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "displayName": "employees",
  • "id": "abc-123",
  • "schemas": [
    ],
  • "meta": {},
  • "members": [
    ]
}

Retrieve a group

Retrieve the specified SCIM group.

path Parameters
id
required
string
Example: abc-123

The unique identifier.

Responses

Request samples 

curl -X GET "https://retool.example.com:3000/api/scim/v2/Groups/1" \
-H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"

Response samples

Content type
application/json
{
  • "displayName": "employees",
  • "id": "abc-123",
  • "schemas": [
    ],
  • "meta": {},
  • "members": [
    ]
}

Replace group members

Replace the members of a group with a specified list of users.

path Parameters
id
required
string
Example: abc-123

The unique identifier.

Request Body schema: application/json
required
displayName
required
string

The display name of the group.

Array of objects

Responses

Request samples

Content type
application/json
{
  • "displayName": "employees",
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "displayName": "employees",
  • "id": "abc-123",
  • "schemas": [
    ],
  • "meta": {},
  • "members": [
    ]
}

Update a group

Update the specified SCIM group.

path Parameters
id
required
string
Example: abc-123

The unique identifier.

Request Body schema: application/json
required
object
op
string
Enum: "add" "replace" "remove"
path
string
Array of objects

Responses

Request samples

Content type
application/json
{
  • "Operations": {
    }
}

Response samples

Content type
application/json
{
  • "displayName": "employees",
  • "id": "abc-123",
  • "schemas": [
    ],
  • "meta": {},
  • "members": [
    ]
}

Delete a group

Delete the specified SCIM group.

path Parameters
id
required
string
Example: abc-123

The unique identifier.

Responses

Request samples 

curl -X DELETE "https://retool.example.com:3000/api/scim/v2/Groups/1" \
-H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"

Users

SCIM users.

List users

Retrieve a list of SCIM users.

query Parameters
filter
string
Example: filter=userName eq "jenny@example.com"

Optional filter parameter

Responses

Request samples 

curl -X GET "https://retool.example.com:3000/api/scim/v2/Users?userName%20eq%20'jenny@example.com'" \
-H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"

Response samples

Content type
application/json
{
  • "totalResults": 25,
  • "itemsPerPage": 1,
  • "startIndex": 0,
  • "schemas": [
    ],
  • "Resources": [
    ]
}

Create a user

Create a new SCIM user.

Request Body schema: application/json
required
userName
string

The user name.

required
Array of objects

A list of email addresses and whether they are the primary one for this user.

required
object
profileUrl
string

The profile image URL for the user.

active
boolean

Whether the user is active.

photos
Array of strings

A list of photo URLs for the user.

profilePhotoUrl
string

The profile image URL for the user.

metadata
object

Metadata about the user.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "nickName": "jenny",
  • "userName": "jennyappleseed",
  • "metadata": { },
  • "name": {
    },
  • "displayName": "Jenny Appleseed",
  • "schemas": [
    ],
  • "id": "abc-123",
  • "externalId": null,
  • "meta": {},
  • "title": null,
  • "timezone": null,
  • "active": true,
  • "photos": [],
  • "emails": [
    ],
  • "groups": [
    ],
  • "profilePhotoUrl": "https://example.com/jenny.png"
}

Retrieve a user

Retrieve the specified SCIM user.

path Parameters
id
required
string
Example: abc-123

The unique identifier.

Responses

Request samples 

curl -X GET "https://retool.example.com:3000/api/scim/v2/Users/USER_ID" \
-H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"

Response samples

Content type
application/json
{
  • "nickName": "jenny",
  • "userName": "jennyappleseed",
  • "metadata": { },
  • "name": {
    },
  • "displayName": "Jenny Appleseed",
  • "schemas": [
    ],
  • "id": "abc-123",
  • "externalId": null,
  • "meta": {},
  • "title": null,
  • "timezone": null,
  • "active": true,
  • "photos": [],
  • "emails": [
    ],
  • "groups": [
    ],
  • "profilePhotoUrl": "https://example.com/jenny.png"
}

Update a user

Update the specified SCIM user. Currently, the only supported field is active.

path Parameters
id
required
string
Example: abc-123

ID of the user to update

Request Body schema: application/json
required
object
op
string
Enum: "add" "replace" "remove"
path
string
Array of objects

Responses

Request samples

Content type
application/json
{
  • "Operations": {
    }
}

Response samples

Content type
application/json
{
  • "nickName": "jenny",
  • "userName": "jennyappleseed",
  • "metadata": { },
  • "name": {
    },
  • "displayName": "Jenny Appleseed",
  • "schemas": [
    ],
  • "id": "abc-123",
  • "externalId": null,
  • "meta": {},
  • "title": null,
  • "timezone": null,
  • "active": true,
  • "photos": [],
  • "emails": [
    ],
  • "groups": [
    ],
  • "profilePhotoUrl": "https://example.com/jenny.png"
}

Delete a user

Delete the specified SCIM user.

path Parameters
id
required
string
Example: abc-123

The unique identifier.

Responses

Request samples 

curl -X DELETE "https://retool.example.com:3000/api/scim/v2/Users/1" \
-H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"