Managing Organization Administrators

Prerequisites: To manage users, groups and roles with the APIs, you need:

The URL of the HID Authentication Service platform (see HID Authentication Service Platforms around the World)
Your tenant ID (the identifier of your tenant, starting with the letter "t", for example, t987198273d986w9869)
A bearer token (access token) obtained by authenticating a privileged user (Organization Administrator, Client ID M2M) through an authentication flow. You need an privileged user to have sufficient permissions to perform the actions in the following sections.
Using a bearer token from an non-privileged user / Client ID will result in 401 / 403 HTTP responses from the HID Authentication Service APIs.
For further information about tokens, see Enabling User Authentication.

Create an Organization Administrator

An Organization Administrator is a special type of user and must be created in the UG_ORGADMIN group and assigned the RL_ORGADMIN role.

In this example, the Organization Administrator is created with only a few attributes (email and Name/Surname). For the full list of possible attributes, see create an end user.

Once the Organization Administrator is created, you need to assign them an authenticator allowing to authenticate with the HID Authentication Service (see Enabling User Authentication).

Copy

POST  https://[base-server-url]/scim/{tenant}/v2/Users HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"

{
    "schemas":[
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:hid:scim:api:idp:2.0:Attribute",
        "urn:hid:scim:api:idp:2.0:UserDevice"   ],
    "externalId":"jsmith@company.com",
    "name":{
        "familyName":"Smith",
        "givenName":"John"   },
    "emails":[
        {
            "value":"jsmith@company.com",
            "type":"work"      }
     ],
     "roles":[
        {"value":"RL_ORGADMIN"}
    ],
    "groups":[
        {"value":"UG_ORGADMIN"}
    ]
}

The response contains the internal ID of the newly created Organization Administrator:

Copy

{
    "schemas":[
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:hid:scim:api:idp:2.0:UserDevice",
        "urn:hid:scim:api:idp:2.0:UserAttribute",
        "urn:hid:scim:api:idp:2.0:UserAuthenticator"   ],
    "id":"49976",
    "externalId":"jsmith@company.com",
    <truncated output>
}

List All Organization Administrators

To list all Organization Administrators, perform a search on the UG_ORGADMIN group:

Copy

POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"groups eq \"UG_ORGADMIN\""}

Search for Organization Administrators

To search for Organization Administrators, use the Users Search endpoint with the UG_ORGADMIN group as the filter.

You can add additional filters with the AND operator.

Examples of filters:

Find all Organization Administrators whose externalId contains "smith":
```
groups eq \"UG_ORGADMIN\" and externalId co \"smith\"
```

Find all Organization Administrators whose familyName starts with "dav":
```
groups eq \"UG_ORGADMIN\" and name.familyName sw \"dav\"
```

Find all Organization Administrators that have a company email address (that ends with "company.com"):
```
groups eq \"UG_ORGADMIN\" and emails ew \"company.com\"
```

For further information, see Searching with the SCIM API.

Update an Organization Administrator

Important:

The HID Authentication Service SCIM API is designed with a replacement approach when it comes to updates.

This means that omitting an attribute that was set on the user on an update request will simply remove/empty this attribute.

The recommended process to update a user is to first fetch the details of this user, and then modify the returned JSON.

First, you need to get the details of the Organization Administrator, either with the internal ID or the externalId.

Copy

POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq \"bdavis@company.com\""}

Copy

The response is a detailed view of the user:

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "resources": [   {
      "schemas":       [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:hid:scim:api:idp:2.0:UserDevice",
         "urn:hid:scim:api:idp:2.0:UserAttribute",
         "urn:hid:scim:api:idp:2.0:UserAuthenticator"      ],
      "id": "49796",
      "externalId": "bdavis@company.com",
      "meta":       {
         "resourceType": "User",
         "created": "2019-09-06T00:00:00Z",
         "location": "https://[base-server-url]/scim/{tenant}/v2/Users/49796",
         "version": "1"      },
      "userName": "bdavis@company.com",
      "name":       {
         "familyName": "Davis",
         "givenName": "Brian"      },
      "displayName": "Brian Davis",
      "title": "M.",
      "active": true,
      "emails": [{"value": "bdavis@company.com"}],
      "phoneNumbers": [{"value": "567 890 654"}],
      "groups": [      {
         "type": "Group",
         "display": "ORGADMIN",
         "value": "UG_ORGADMIN",
         "$ref": "https://[base-server-url]/scim/{tenant}/v2/Groups/UG_ORGADMIN"      }],
      "roles": [ {
         "type": "Role",
         "display": "ORGADMIN",
         "value": "RL_ORGADMIN",
         "$ref": "https://[base-server-url]/scim/{tenant}/v2/Roles/RL_ORGADMIN"      }],
      "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":       [
                  {
            "name": "ATR_EMAIL",
            "type": "string",
            "value": "bdavis@company.com",
            "readOnly": false
         },
                  {
            "name": "LASTNAME",
            "type": "string",
            "value": "Davis",
            "readOnly": false
         },
                  {
            "name": "FIRSTNAME",
            "type": "string",
            "value": "Brian",
            "readOnly": false
         },
                  {
            "name": "TITLE",
            "type": "string",
            "value": "M.",
            "readOnly": false
         },
                  {
            "name": "ATR_MOBILE",
            "type": "string",
            "value": "567 890 654",
            "readOnly": false
         }
      ]},
      "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
      "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
   }]
}

Reuse the JSON-based response by updating the required attributes with a PUT request. The internal ID is used as a path parameter of the query.

Note:

The externalId cannot be updated and it is recommended that you avoid changing the emails if you use it as an externalId
Instead, delete the user and create another one with the correct email / external ID
The following fields are immutable and, to change their value, update the corresponding extra attributes with urn:hid:scim:api:idp:2.0:UserAttribute:
- name (object):
  - familyName and givenName
- title - the title (M., Ms., Dr. ...)
- emails (array of objects):
  - value and type (work, personal ...)
- phoneNumbers (array of objects):
  - value
Devices and authenticators can also be updated (see Enabling User Authentication)

In the following example, the email address, the family and first names, the title, and the phone number are changed.

Copy

PUT https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:UserDevice",
      "urn:hid:scim:api:idp:2.0:UserAttribute",
      "urn:hid:scim:api:idp:2.0:UserAuthenticator"   ],
   "id":"49796",
   "externalId":"bdavis@company.com",
   "meta":{
      "resourceType":"User",
      "created":"2019-09-06T00:00:00Z",
      "location":"https://[base-server-url]/scim/{tenant}/v2/Users/49796",
      "version":"1"   },
   "userName":"bdavis@company.com",
   "name":{
      "familyName":"Davis",
      "givenName":"Brian"   },
   "displayName":"Brian Davis",
   "title":"M.",
   "active":true,
   "emails":[
      {
         "value":"bdavis@company.com"      }
   ],
   "phoneNumbers":[
      {
         "value":"567 890 654"      }
   ],
   "urn:hid:scim:api:idp:2.0:UserAttribute":{
      "attributes":[
         {
            "name":"ATR_EMAIL",
            "type":"string",
            "value":"bdavis-second@company.com",
            "readOnly":false
         },
         {
            "name":"LASTNAME",
            "type":"string",
            "value":"Davis Stephan",
            "readOnly":false
         },
         {
            "name":"FIRSTNAME",
            "type":"string",
            "value":"Brian John",
            "readOnly":false
         },
         {
            "name":"TITLE",
            "type":"string",
            "value":"Mr",
            "readOnly":false
         },
         {
            "name":"ATR_MOBILE",
            "type":"string",
            "value":"897 678 456",
            "readOnly":false
         }
      ]
   },
   "urn:hid:scim:api:idp:2.0:UserAuthenticator":{
      "authenticators":[
      ]
   },
   "urn:hid:scim:api:idp:2.0:UserDevice":{
      "devices":[
      ]
   }
}

Delete an Organization Administrator

Important: Do not use this method to delete Client IDs!

You will delete the user but would leave an orphan Client ID "configuration" in the background. This orphan configuration might prevent you from re-creating a Client ID with the same externalId.

For further information, see Delete a Client ID.

First, search for the Organization Administrator to get their internal ID:

Copy

POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq \"bdavis@company.com\""}

The response contains the internal ID (in this example, 49796):

Copy

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "resources": [   {
      "schemas":       [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:hid:scim:api:idp:2.0:UserDevice",
         "urn:hid:scim:api:idp:2.0:UserAttribute",
         "urn:hid:scim:api:idp:2.0:UserAuthenticator"      ],
      "id": "49796",
      "externalId": "bdavis@company.com",
      
      (...)
}

Use this internal ID as a path parameter of a DELETE request.

Copy

DELETE https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN