Overview

Using SureCloud’s REST API it is possible to create and update (patch) SureCloud user accounts.

To access any of the services on the API the user must be authenticated to the SureCloud platform. Two methods are available for this and are explained here.

The API requires an Accept and Content-Type header of 'application/json' to be sent.

'Accept: application/json'
'Content-Type: application/json'

Creating and Updating User Accounts

To create or modify one or more SureCloud user accounts, make a HTTP PATCH request to the user resource specifying a JSON formatted data payload which details the accounts you wish to create or update:

https://secure.surecloud.com/restful/v1/user

 You can use this resource directly using the API with a cURL command:

curl -X PATCH --header 'Content-Type: application/json' 
--header 'Authorization: Bearer <JWTHere>' 
--header 'Accept: application/json;charset=UTF-8' 
-d '<JSON formatted user account information here>'
'https://secure.surecloud.com/restful/v1/user'

Or alternatively use our Swagger documentation's "Try it out!" feature where you can also find a full list of account attributes that can be included in the data body.

Example

curl -X PATCH --header 'Content-Type: application/json' --header 'Authorization: Bearer <JWTHere>' --header 'Accept: application/json' -d '{ \
   "users": [ \
     { \
      "email": "johndoe@example.com",
      "enabled": true,
      "name": "John Doe",
      "jobTitle": "Analyst",
      "groups":["//Risk Department/Risk Analysts"],
      "role": "CONTRIBUTOR"     } \
   ] \
 }' 'https://secure.surecloud.com/restful/v1/user'

Result

Making a successful call to the User resource will result in a Response Code of 200 and return a body containing the user model. For example:

[
  {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "enabled": true,
    "jobTitle": "Analyst",
    "role": "CONTRIBUTOR",
    "personType": "INTERNAL",
    "groups": [
      "//Risk Department/Risk Analysts"
    ]
  }
]

Groups

Groups are specified as paths that are case-sensitive in the following format:

//Parent Group Name/GroupName

Groups are processed individually, and may fail validation individually. Any error will be reported in the patchErrorMessage property.

Mandatory attributes

• Account creation requires email and role to be specified
• Account modification requires email or userID to be specified (used to identify the account)

Note - Account attributes that are non-mandatory remain as set unless explicitly set in the PATCH body with one exception; personType will default back to "INTERNAL" if not specified during account creation or modification.

Useful links:

API Authentication