SCIM 2.0 API Reference
View reference information for the subset of the SCIM 2.0 API that Retool uses.
Retool implements a subset of the SCIM 2.0 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.
Authorization
Define a SCIM_AUTH_TOKEN and attach it as a bearer token in all API keys using the header.
Example curl request:
curl http://localhost:3000/api/scim/v2/someEndpoint \
-H 'authorization: Bearer yourSecretAuthToken'
Listing users
GET /api/scim/v2/Users/
--- Example basic CURL request
curl http://localhost:3000/api/scim/v2/Users \
-H 'Authorization: Bearer yourSecretAuthToken'
--- Optional filter parameter to search by a userName (typically the email of the user)
curl 'http://localhost:3000/api/scim/v2/Users?filter=userName%20eq%20"[email protected]"'
-H 'Authorization: Bearer yourSecretAuthToken'
--- Example payload
{
"schemas" : [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"startIndex" : 1,
"Resources" : [
{
"nickName" : "John",
"userName" : "[email protected]",
"displayName" : "John Doe",
"externalId" : null,
"groups" : [
{
"display" : "Retool - production - admin",
"value" : 1
},
{
"value" : 4,
"display" : "Retool - production - All Users"
},
{
"value" : 5,
"display" : "Retool - production - Sales"
}
],
"emails" : [
{
"value" : "[email protected]",
"primary" : true
}
],
"timezone" : null,
"meta" : {
"location" : "https://api.scimapp.com/scim/v1/Users/1",
"created" : "2020-01-12T00:49:59.357Z"
},
"title" : null,
"schemas" : [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"name" : {
"givenName" : null,
"familyName" : null
},
"active" : true,
"profileUrl" : null,
"id" : "user_7beab5e5a3424d4cac4238ec312a8b8a",
"photos" : []
}
],
"totalResults" : 1,
"itemsPerPage" : 1
}
Creating a user
POST /api/scim/v2/Users/
--- Example basic CURL request
curl -X POST \
http://localhost:3000/api/scim/v2/users \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"userName": "[email protected]",
"active": true,
"emails": [{ "value": "[email protected]" }],
"name": "John Doe",
"profileUrl": "https://en.wikipedia.org/wiki/Smiley#/media/File:SNice.svg"
}'
--- Example payload
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "user_1dc433e85dcc4d7e9334e519847d498c",
"externalId": null,
"meta": {
"created": "2020-06-10T19:12:00.835Z",
"location": "https://api.scimapp.com/scim/v1/Users/2"
},
"userName": "[email protected]",
"nickName": null,
"name": {
"givenName": null,
"familyName": null
},
"displayName": "null undefined",
"profileUrl": "https://en.wikipedia.org/wiki/Smiley#/media/File:SNice.svg",
"title": null,
"timezone": null,
"active": true,
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"photos": [],
"groups": []
}
Looking a up an user by their ID
GET /api/scim/v2/Users/{id}
--- Example curl request
curl -X GET \
http://localhost:3000/api/scim/v2/Users/user_1dc433e85dcc4d7e9334e519847d498c \
-H 'authorization: Bearer yourSecretAuthToken' \
--- Example payload
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "user_1dc433e85dcc4d7e9334e519847d498c",
"externalId": null,
"meta": {
"created": "2020-06-10T19:12:00.835Z",
"location": "https://api.scimapp.com/scim/v1/Users/2"
},
"userName": "[email protected]",
"nickName": null,
"name": {
"givenName": null,
"familyName": null
},
"displayName": "null undefined",
"profileUrl": "https://en.wikipedia.org/wiki/Smiley#/media/File:SNice.svg",
"title": null,
"timezone": null,
"active": true,
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"photos": [],
"groups": []
}
Modifying a user's properties
PUT /api/scim/v2/Users/{id}
--- Example curl request
curl -X PUT \
http://localhost:3000/api/scim/v2/users/user_1dc433e85dcc4d7e9334e519847d498c \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"userName": "[email protected]",
"active": true,
"emails": [{ "value": "[email protected]", "primary": true }],
"name": "John Doe",
"profileUrl": "https://en.wikipedia.org/wiki/Smiley#/media/File:SNice.svg"
}'
--- Example payload
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "user_1dc433e85dcc4d7e9334e519847d498c",
"externalId": null,
"meta": {
"created": "2020-06-10T19:12:00.835Z",
"location": "https://api.scimapp.com/scim/v1/Users/2"
},
"userName": "[email protected]",
"name": {},
"displayName": "undefined undefined",
"title": null,
"timezone": null,
"active": true,
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"photos": [],
"groups": []
}
Disabling or enabling a user
PATCH /api/scim/v2/Users/{id}
--- Example request to disable a user
curl -X PATCH \
http://localhost:3000/api/scim/v2/users/user_1dc433e85dcc4d7e9334e519847d498c \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"Operations": [
{
"op": "replace",
"value": {
"active": false
}
}
]
}'
--- Example request to enable a user
curl -X PATCH \
http://localhost:3000/api/scim/v2/users/user_1dc433e85dcc4d7e9334e519847d498c \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"Operations": [
{
"op": "replace",
"value": {
"active": true
}
}
]
}'
List all groups
GET /api/scim/v2/Groups
--- Example request
curl -X GET \
http://localhost:3000/api/scim/v2/groups \
-H 'authorization: Bearer yourSecretAuthToken' \
--- Example payload
{
"totalResults": 5,
"itemsPerPage": 5,
"startIndex": 1,
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"Resources": [
{
"id": 1,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - admin",
"members": [
{
"value": "[email protected]",
"display": "null undefined"
}
],
"meta": {
"created": "2020-01-12T00:49:27.226Z"
}
},
{
"id": 2,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - editor",
"members": [],
"meta": {
"created": "2020-01-12T00:49:27.226Z"
}
},
{
"id": 3,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - viewer",
"members": [],
"meta": {
"created": "2020-01-12T00:49:27.226Z"
}
},
{
"id": 4,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - All Users",
"members": [
{
"value": "[email protected]",
"display": "null undefined"
},
{
"value": "[email protected]",
"display": "null undefined"
}
],
"meta": {
"created": "2020-01-12T00:49:27.226Z"
}
},
{
"id": 5,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - Sales",
"members": [
{
"value": "[email protected]",
"display": "null undefined"
}
],
"meta": {
"created": "2020-04-11T00:07:52.512Z"
}
}
]
}
Look up an individual group
GET /api/scim/v2/Groups/{groupId}
--- Example request
curl -X GET \
http://localhost:3000/api/scim/v2/groups/1 \
-H 'authorization: Bearer yourSecretAuthToken' \
--- Example payload
{
"id": 1,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - admin",
"members": [
{
"value": "[email protected]",
"display": "null undefined"
}
],
"meta": {
"created": "2020-01-12T00:49:27.226Z"
}
}
Create a group
POST /api/scim/v2/Groups
--- Example request
curl -X POST \
http://localhost:3000/api/scim/v2/groups \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"displayName": "Support Group Tier 1",
"members": [{ "display": "[email protected]" }, { "display": "[email protected]" }]
}'
--- Example payload
{
"id": 8,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Retool - production - Support Group Tier 1",
"meta": {
"created": "2020-06-10T19:32:42.848Z"
}
}
Adding, removing, and setting the members of a group
PATCH /api/scim/v2/Groups/{groupId}
--- Example request of removing a user from a group
curl -X PATCH \
http://localhost:3000/api/scim/v2/groups/8 \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"Operations": [{
"op": "remove",
"path": "members[value eq \"user_1dc433e85dcc4d7e9334e519847d498c\"]"
}]
}'
--- Example request of adding a user to a group
curl -X PATCH \
http://localhost:3000/api/scim/v2/groups/8 \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"Operations": [{
"op": "add",
"path": "members[value eq \"user_1dc433e85dcc4d7e9334e519847d498c\"]"
}]
}'
--- Example request of completely replacing all the members in a group in one call
curl -X PATCH \
http://localhost:3000/api/scim/v2/groups/8 \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"Operations": [{
"op": "replace",
"path": "members",
"value": [{
"display": "[email protected]"
}, {
"display": "[email protected]"
}]
}]
}'
--- Example request of updating the name of a group
curl -X PATCH \
http://localhost:3000/api/scim/v2/groups/8 \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'content-type: application/json' \
-d '{
"Operations": [{
"op": "replace",
"value": {
"displayName": "New Group Name"
}
}]
}'
Deleting a group
DELETE /api/scim/v2/Groups/{groupId}
--- Example request
curl -X DELETE \
http://localhost:3000/api/scim/v2/groups/8 \
-H 'authorization: Bearer yourSecretAuthToken' \
-H 'cache-control: no-cache
Updated 18 days ago