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.
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.
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.
The SCIM 2.0 API does not support pagination. Parameters such as count
and startIndex
are ignored.
Request samples
- curl
curl -X GET "https://retool.example.com:3000/api/scim/v2/Groups" \ -H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18"
Response samples
- 200
{- "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",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
]
}
Create a group
Create a new SCIM group.
Authorizations:
Request Body schema: application/jsonrequired
displayName required | string (DisplayName) The display name of the group. |
Array of objects (Member) |
Responses
Request samples
- Payload
- curl
{- "displayName": "employees",
- "members": [
- {
- "value": "abc-123",
- "display": "Jenny Appleseed"
}
]
}
Response samples
- 200
{- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
Retrieve a group
Retrieve the specified SCIM group.
Authorizations:
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
{- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
Replace group members
Replace the members of a group with a specified list of users.
Authorizations:
path Parameters
id required | string (ObjectId) Example: abc-123 The unique identifier. |
Request Body schema: application/jsonrequired
displayName required | string (DisplayName) The display name of the group. |
Array of objects (Member) |
Responses
Request samples
- Payload
- curl
{- "displayName": "employees",
- "members": [
- {
- "value": "abc-123",
- "display": "Jenny Appleseed"
}
]
}
Response samples
- 200
{- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
Update a group
Update the specified SCIM group.
Authorizations:
path Parameters
id required | string (ObjectId) Example: abc-123 The unique identifier. |
Request Body schema: application/jsonrequired
object | |||||||
|
Responses
Request samples
- Payload
- curl
{- "Operations": {
- "op": "add",
- "path": "string",
- "value": [
- {
- "value": "string",
- "display": "string"
}
]
}
}
Response samples
- 200
{- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
Delete a group
Delete the specified SCIM group.
Authorizations:
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"
List users
Retrieve a list of SCIM users.
Authorizations:
query Parameters
filter | string Example: filter=userName eq "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
{- "totalResults": 25,
- "itemsPerPage": 1,
- "startIndex": 0,
- "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "Resources": [
- {
- "nickName": "jenny",
- "userName": "jennyappleseed",
- "metadata": { },
- "name": {
- "givenName": "Jenny",
- "familyName": "Appleseed"
}, - "displayName": "Jenny Appleseed",
- "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "id": "abc-123",
- "externalId": null,
- "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "title": null,
- "timezone": null,
- "active": true,
- "emails": [
- {
- "primary": true,
- "value": "jenny@example.com"
}
], - "groups": [
- {
- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
],
}
]
}
Create a user
Create a new SCIM user.
Authorizations:
Request Body schema: application/jsonrequired
userName | 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 | string (UserProfileUrl) The profile image URL for the user. |
active | boolean (UserActive) Whether the user is active. |
photos | Array of strings (UserPhotos) A list of photo URLs for the user. |
profilePhotoUrl | string (UserProfileUrl) The profile image URL for the user. |
metadata | object (UserMetadata) Metadata about the user. |
Responses
Request samples
- Payload
- curl
{- "userName": "jennyappleseed",
- "emails": [
- {
- "primary": true,
- "value": "jenny@example.com"
}
], - "name": {
- "givenName": "Jenny",
- "familyName": "Appleseed"
}, - "active": true,
- "metadata": { }
}
Response samples
- 200
{- "nickName": "jenny",
- "userName": "jennyappleseed",
- "metadata": { },
- "name": {
- "givenName": "Jenny",
- "familyName": "Appleseed"
}, - "displayName": "Jenny Appleseed",
- "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "id": "abc-123",
- "externalId": null,
- "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "title": null,
- "timezone": null,
- "active": true,
- "emails": [
- {
- "primary": true,
- "value": "jenny@example.com"
}
], - "groups": [
- {
- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
],
}
Retrieve a user
Retrieve the specified SCIM user.
Authorizations:
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
{- "nickName": "jenny",
- "userName": "jennyappleseed",
- "metadata": { },
- "name": {
- "givenName": "Jenny",
- "familyName": "Appleseed"
}, - "displayName": "Jenny Appleseed",
- "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "id": "abc-123",
- "externalId": null,
- "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "title": null,
- "timezone": null,
- "active": true,
- "emails": [
- {
- "primary": true,
- "value": "jenny@example.com"
}
], - "groups": [
- {
- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
],
}
Update a user
Update the specified SCIM user. Currently, the only supported field is active
.
Authorizations:
path Parameters
id required | string (ObjectId) Example: abc-123 ID of the user to update |
Request Body schema: application/jsonrequired
object | |||||||
|
Responses
Request samples
- Payload
- curl
{- "Operations": {
- "op": "add",
- "path": "string",
- "value": [
- {
- "value": "string",
- "display": "string"
}
]
}
}
Response samples
- 200
{- "nickName": "jenny",
- "userName": "jennyappleseed",
- "metadata": { },
- "name": {
- "givenName": "Jenny",
- "familyName": "Appleseed"
}, - "displayName": "Jenny Appleseed",
- "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
], - "id": "abc-123",
- "externalId": null,
- "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "title": null,
- "timezone": null,
- "active": true,
- "emails": [
- {
- "primary": true,
- "value": "jenny@example.com"
}
], - "groups": [
- {
- "displayName": "employees",
- "id": "abc-123",
- "schemas": [
- [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
], - "meta": {
- "created": "2020-06-10T19:12:00.835Z",
}, - "members": [
- {
- "value": "user@domain.com",
- "display": "Jenny Appleseed"
}
]
}
],
}
Delete a user
Delete the specified SCIM user.
Authorizations:
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"