Using SCIM API Provisioning

This page contains information on how to use Postman, a popular API platform to provision your users into your Keeper tenant.

Setting up the Environment

  1. Open Postman

  2. Create a New Request

  • Method: GET , POST, DELETE, PATCH or PUT

  • URL: https://keepersecurity.com/api/rest/scim/v2/<node_id>

Depending on the data center of your Keeper tenant, the domain will change. US: keepersecurity.com EU: keepersecurity.eu AU: keepersecurity.com.au JP: keepersecurity.jp CA: keepersecurity.ca GOV: govcloud.keepersecurity.us

  1. Set the Headers

Key
Value

Authorization

Bearer YOUR_AUTH_TOKEN

Content-Type

application/scim+json

  1. Set the Body

  • Choose raw and select JSON format.

Adding a User - Users/POST

  1. Set the HTTP Method and URL

  • Set the HTTP method to POST using the dropdown menu.

  • Enter the URL for adding a user:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users

Be sure to replace <node_id> with your actual node ID where you want the user added. This Node ID is provided to you on the SCIM setup page in the Keeper Admin Console, or it can be found using Keeper Commander's "enterprise-info --nodes" command.

  1. Set the Body

  • Click on the "Body" tab below the URL field

  • Choose raw and select JSON format

  • Add the JSON body with the details of the user you want to add. Here's an example JSON body:

{
 "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User",
   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
 ],
 "userName": "<user_email>",
 "displayName": "<user_name>",
 "externalId": "",
 "name": {
   "familyName": "<first_name>",        
   "givenName": "<last_name>"              
 },
 "emails":[
 	{
 		"value":"email@domain.com"
 	}
 ],
 "roles": "<role_ids>",
 "groups":[
    {
      "value":"<group_id>",
      "$ref":"http://keepersecurity.com/api/rest/scim/v2/<node_id>/<group_id>/scim/Groups",
      "display":"<team_name>"
    }
 ]
}

You can also add the user to a team upon creation by including the <group_id> for "value" in the groups object. This is the only required information to add the user to a group. "$ref" and "display" are optional

  1. Send the Request

Response HTTP codes

HTTP code

Meaning

201

Created

success

409

Conflict

Email already taken

428

Precondition Required

Number of licensed seats was exceeded.

Locking/Unlocking a user - Users/PATCH

  1. Set the Method to PATCH and the URL to the following:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users/<user_id>

  1. Set the body of the JSON request

  • Choose raw and select JSON format

  • Add the JSON body with the details of the user you want to add. Here's an example JSON body:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "active",
      "value": "true"
    }
  ]
}

Be sure to set the "value" to true (unlocked) or false (locked)

  1. Send the request

Retrieve information about a user/users - Users/GET

  1. Open Postman and set the HTTP method to GET

  • For a information about all the users in a node, use the following URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users

  • For information on a specific user, specify the user ID 

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users/<user_id>

  1. Send the request

We also support filter for users, below is an example for searching based on user id:

https://keepersecurity.com/api/rest/scim/v2/<node_ID>/Users?filter=id+eq+%22<user_ID>%22

Additionally, you can use pagination by using startIndex and count:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users?startIndex=2&count=200

Retrieve Groups & Group ID’s - Groups/GET

  1. Open Postman and create a new GET request

  • Set the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups

  1. Send the request

Expected Response

The response will be a JSON object containing details of all groups under the specified node. The "id" field within each group object represents the group ID. In Keeper, a group is represented by a Keeper Team object. The ID is the Keeper Team UID.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "group_id_1",
      "displayName": "Group 1",
      "members": []
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "group_id_2",
      "displayName": "Group 2",
      "members": []
    }
  ]
}

To get the information of a single group, include the group ID at the end of the URL. https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups/<group_id>

Creating a Team - Groups/POST

  1. Create a New Request

  • Click on "New" and then select "Request" from the dropdown menu.

  • Alternatively, you can click on the "Request" tab if it is already open

  1. Set the HTTP Method and URL

  • Set the HTTP method to POST using the dropdown menu

  • Enter the URL for adding a team

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups

  1. Set the Body

  • Click on the "Body" tab below the URL field.

  • Choose raw and select JSON format.

  • Add the JSON body with the details of the team you want to create. Here's an example JSON body:

{
	"schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/Group"
     ],
     "displayName": "<team_name>",
	 "externalId": "dfe9166c-57f9-417d-83a6-072b5a56a4fe"
}

Replace "Team Name" with the desired team name.

  1. Send the Request

  • Click on the "Send" button in Postman to execute the request

Deleting a team - Groups/DELETE

  1. Set the HTTP Method and URL

  • Set the HTTP method to DELETE using the dropdown menu.

  • Set the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups/<group_id>

  1. Send the request

Adding or removing a user to a team - Users/PATCH

  1. Set the HTTP Method and URL

  • Set the HTTP method to PATCH using the dropdown menu.

  • Set the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Groups/<group_id>

Replace <node_id> with your actual node ID and <group_id> with the ID of the team you want to update

  1. Set the Body

  • Click on the "Body" tab below the URL field

  • Choose raw and select JSON format

  • Add the JSON body with the details of the user you want to add to the team. Here's an example JSON body:

{
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "<user_id>"
        }
      ]
    }
  ]
}

Changing the "op" value to "add" will add a user to a team. Changing the value to "remove" will remove a user from the team

  1. Send the request

Updating User Attributes - Users/PUT

  1. Create a New Request

  • Click on "New" and then select "Request" from the dropdown menu.

  • Alternatively, you can click on the "Request" tab if it is already open.

  1. Set the HTTP Method and URL

  • Set the HTTP method to PUT.

  • Use the URL:

https://keepersecurity.com/api/rest/scim/v2/<node_id>/Users/<user_id>

  1. Set the Body

  • Click on the "Body" tab below the URL field

  • Choose raw and select JSON format

Here is an example of the JSON body to update the user information:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "email@domain.com",
  "displayName": "<Desired display name>",
  "externalId":
  
  "name": {
    "familyName": "<First Name>",        
    "givenName": "<Last Name>"              
 },
  "emails": [
    {
      "value": "<email@domain.com>",
      "primary": true
    }
  ],
  "roles":"none" | "123,432,4324,654", 
  "groups":[
    {
      "value":"<group_id>",
      "$ref":"http://keepersecurity.com/api/rest/scim/v2/<node_id>/<group_id>/scim/Groups",
      "display":"<group_name>"}
    }
 ]
  "active": true
}

Changing the "active" flag to false will lock the user account, changing it to true will unlock the account

  1. Send the request

  • Click on the "Send" button in Postman to execute the request

Updating User Attributes - Users/Patch

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "userName",
      "value": "<user_name>"
    },
    {
      "op": "replace",
      "path": "displayName",
      "value": "<display_name>"
    },
    {
      "op": "replace",
      "path": "externalId",
      "value": "<external_Id>"
    },
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "<last_name>"
    },
    {
      "op": "replace",
      "path": "name.givenName",
      "value": "<first_name>"
    },
    {
      "op": "replace",
      "path": "active",
      "value": false
    },
    {
      "op": "add",
      "path": "groups",
      "value": [
        {
          "$ref": "https://example.com/v2/Users/1743756723210",
          "value": "<group_id>"
        }
      ]
    },
    {
      "op": "remove",
      "path": "groups",
      "value": [
        {
          "$ref": "https://example.com/v2/Users/<user_id>",
          "value": "<group_id>"
        }
      ]
    }
  ]
}

SCIM related endpoints/GET

  • Set the HTTP method to Get

  • Use the URL:

ServiceProviderConfig / ResourceTypes (User/Group) / Schemas

https://keepersecurity.com/api/rest/scim/v2/<node_id>/ServiceProviderConfig
https://keepersecurity.com/api/rest/scim/v2/<node_id>/ResourceTypes/User
https://keepersecurity.com/api/rest/scim/v2/<node_id>/ResourceTypes/Group
https://keepersecurity.com/api/rest/scim/v2/<node_id>/Schemas/urn:ietf:params:scim:schemas:core:2.0:User
https://keepersecurity.com/api/rest/scim/v2/<node_id>/Schemas
PreviousAPI Provisioning with SCIMNextTeam and User Approvals

Last updated

Was this helpful?