Retool SCIM 2.0 API (1.0.0)

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.

Authorizations:

BearerAuth

Responses

Request samples

curl

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

Response samples

200

Content type

application/json

{"totalResults": 25,
"itemsPerPage": 1,
"startIndex": 0,
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}
]
}

Create a group

Create a new SCIM group.

Authorizations:

BearerAuth

Request Body schema: application/json
required

displayName required	string (DisplayName) The display name of the group.
	Array of objects (Member)

Responses

Request samples

Payload
curl

Content type

application/json

{"displayName": "employees",
"members": [{"value": "abc-123",
"display": "Jenny Appleseed"
}
]
}

Response samples

200

Content type

application/json

{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}

Retrieve a group

Retrieve the specified SCIM group.

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

Example: abc-123

The unique identifier.

Responses

Request samples

curl

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

Response samples

200

Content type

application/json

{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}

Replace group members

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

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

Example: abc-123

The unique identifier.

Request Body schema: application/json
required

displayName required	string (DisplayName) The display name of the group.
	Array of objects (Member)

Responses

Request samples

Payload
curl

Content type

application/json

{"displayName": "employees",
"members": [{"value": "abc-123",
"display": "Jenny Appleseed"
}
]
}

Response samples

200

Content type

application/json

{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}

Update a group

Update the specified SCIM group.

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

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

Payload
curl

Content type

application/json

{"Operations": {"op": "add",
"path": "string",
"value": [{"value": "string",
"display": "string"
}
]
}
}

Response samples

200

Content type

application/json

{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}

Delete a group

Delete the specified SCIM group.

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

Example: abc-123

The unique identifier.

Responses

Request samples

curl

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.

Authorizations:

BearerAuth

query Parameters

filter

string

Example: filter=userName%20eq%20"jenny@example.com"

Optional filter parameter

Responses

Request samples

curl

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

200

Content type

application/json

{"totalResults": 25,
"itemsPerPage": 1,
"startIndex": 0,
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [{"nickName": "jenny",
"metadata": { },
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"id": "abc-123",
"externalId": null,
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Users/1"
},
"title": null,
"timezone": null,
"active": true,
"photos": ["https://example.com/jenny.png"
],
"groups": [{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}
]
}
]
}

Create a user

Create a new SCIM user.

Authorizations:

BearerAuth

Request Body schema: application/json
required

userName required	string (UserUserName) The user name.
required	Array of objects (UserEmail) A list of email addresses and whether they are the primary one for this user.
required	object (UserName)
profileUrl required	string (UserProfileUrl) The profile URL for the user.

Responses

Request samples

Payload
curl

Content type

application/json

{"userName": "jennyappleseed",
"email": [{"primary": true,
"value": "jenny@example.com"
}
],
"name": {"givenName": "Jenny",
"familyName": "Appleseed"
},
"profileUrl": "https://example.com/jenny.png"
}

Response samples

200

Content type

application/json

{"nickName": "jenny",
"metadata": { },
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"id": "abc-123",
"externalId": null,
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Users/1"
},
"title": null,
"timezone": null,
"active": true,
"photos": ["https://example.com/jenny.png"
],
"groups": [{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}
]
}

Retrieve a user

Retrieve the specified SCIM user.

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

Example: abc-123

The unique identifier.

Responses

Request samples

curl

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

Response samples

200

Content type

application/json

{"nickName": "jenny",
"metadata": { },
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"id": "abc-123",
"externalId": null,
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Users/1"
},
"title": null,
"timezone": null,
"active": true,
"photos": ["https://example.com/jenny.png"
],
"groups": [{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}
]
}

Update a user

Update the specified SCIM user.

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

Example: abc-123

ID of the user to update

Request Body schema: application/json
required

userName required	string (UserUserName) The user name.
required	Array of objects (UserEmail) A list of email addresses and whether they are the primary one for this user.
required	object (UserName)
profileUrl required	string (UserProfileUrl) The profile URL for the user.

Responses

Request samples

Payload
curl

Content type

application/json

{"userName": "jennyappleseed",
"email": [{"primary": true,
"value": "jenny@example.com"
}
],
"name": {"givenName": "Jenny",
"familyName": "Appleseed"
},
"profileUrl": "https://example.com/jenny.png"
}

Response samples

200

Content type

application/json

{"nickName": "jenny",
"metadata": { },
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"id": "abc-123",
"externalId": null,
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Users/1"
},
"title": null,
"timezone": null,
"active": true,
"photos": ["https://example.com/jenny.png"
],
"groups": [{"displayName": "employees",
"id": "abc-123",
"schemas": [["urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
],
"meta": {"created": "2020-06-10T19:12:00.835Z",
"location": "https://retool.example.com/scim/v1/Groups/1"
}
}
]
}

Delete a user

Delete the specified SCIM user.

Authorizations:

BearerAuth

path Parameters

id

required

string (ObjectId)

Example: abc-123

The unique identifier.

Responses

Request samples

curl

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

Retool SCIM 2.0 API (1.0.0)

Base URL

Authentication

Pagination

Groups

List groups

Authorizations:

Responses

Request samples

Response samples

Create a group

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Retrieve a group

Authorizations:

path Parameters

Responses

Request samples

Response samples

Replace group members

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update a group

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete a group

Authorizations:

path Parameters

Responses

Request samples

Users

List users

Authorizations:

query Parameters

Responses

Request samples

Response samples

Create a user

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Retrieve a user

Authorizations:

path Parameters

Responses

Request samples

Response samples

Update a user

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete a user

Authorizations:

path Parameters

Responses

Request samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required