SmartSense API: SCIM API v2
SmartSense Identity Management with SCIM v2
To ease the managing of SmartSense users, SmartSense provides a set of endpoints that conform to the SCIM version 2 standard.
Results Paging
Per SCIM RFC 7644 any endpoint that returns a list of data is subject to paging. Paging information is included in all paged responses as follows.
| Name | Type | Description |
|
totalResults |
integer (32 bit) | The total number of results matching the client query. |
| startIndex | integer (32 bit) | The 1-based index of the first result in the current page. |
| itemsPerPage | integer (32 bit) | The number of results returned in the current page. |
SCIM Specific Types
SCIM objects and their attributes are defined by SCIM RFC 7643. Listed here is a description of the SCIM types used in SmartSense's SCIM implementation and how they are used.
Meta
All SCIM objects have contain a meta object. This object is not required for PUTs, POSTs, or PATCHes, but will always be returned with GETs.
| Name | Type | Mutability | Description |
|
resourceType |
string | ReadOnly | The name of the containing resource's type. |
| location | string | ReadOnly | A URL that can be used to GET the object. |
SmartSenseEnterpriseUser
SmartSenseEnterpriseUser is an extension of the basic SCIM Enterprise User schema. SmartSenseEnterpriseUser consists of two attributes.
| Name | Type | Mutability | Description |
| defaultContactRoleId | string | ReadWrite | A ContactRoleId that will be used when assigning the User to a Group. |
Name
| Name | Type | Mutability | Description |
|
givenName |
string | ReadWrite | The User's first name. |
| familyName | string | ReadWrite | The User's last name. |
| Name | Type | Mutability | Description |
|
value |
string | ReadWrite | The User's email address. |
| type | string | ReadWrite | The type of email address. Should always be "work." |
| primary | boolean | ReadWrite | A boolean indicating if this email is the primary email for the User. Should always be "true." |
Phone Number
SmartSense Users can be configured with two phone numbers: one for voice calls and one for SMS. An SMS phone number should have its "type" set to "SMS." A voice call phone number should have its "type" set to "voice."
| Name | Type | Mutability | Description |
|
value |
string | ReadWrite | The User's phone number. 1 |
| type | string | ReadWrite | The type of phone number address. Should either be "SMS" or "voice." |
| primary | boolean | ReadWrite | A boolean indicating if this phone number is the primary phone number for the User. Should always be "true." |
1 Must be in international format. May begin with '+', followed by digits; other characters will be discarded. 10-digit-long values not starting with '+' will have the characters '+1' appended at the beginning, e.g. '2015551234' -> '+12015551234'. Other values not starting with '+' will have a single '+' character appended at the beginning, e.g. '59812345678' -> '+5981234567
8'
Access Role
The Access Role endpoint is used to get all SmartSense Access Roles. A User's assigned Access Role defines what access and permissions they have in the SmartSense application.
Get all Access Roles
Get all supported roles.
GET /scim/v2/accessRole
Parameters:
None
Output Fields:
| Property | Type | Description |
|
key |
string | The Role's Name. |
| Value | string | A description of the Role. |
Contact Role
The Contact Role endpoints are used to create and update ContactRoles from the SmartSense system. Contact Roles define the relationship the User has with a Group. When a User is assigned to a Group, they must also be assigned a Contact Role. These ContactRoles are used to determine who should be notified when an Asset enters an alarm state.
A single Contact Role can be assigned to a User for all the Groups they are assigned to by setting the DefaultContactRoleId field in the SmartSenseEnterpriseUser object.
ContactRoleObjectModel
| Name | Type | Mutability | Description |
|
id |
string | ReadOnly | A globally unique identifier of the ContactRole. |
| name | string | Immutable | The name of the ContactRole that is displayed in the SmartSense application. |
Get One Contact Role
Get a single ContactRole identified by the given ContactRoleId.
GET /scim/v2/contactRole/{contactRoleId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
contactRoleID |
path |
string | yes | Unique identifier of the requested ContactRole. |
Output Fields:
| Name | Type | Description |
|
|
ContactRole | A ContactRole object for the requested Contact Role. |
Get All Contact Roles
Gets all the ContactRoles within the Account, one page at a time.
GET scim/v2/contactRole
Parameters shown below:
| Name | Location | Type | Required | Description |
|
startIndex |
query string |
integer (32 bit) | no | 1-based index of where to start the page. Defaults to 1. |
|
count |
query string |
integer (32 bit) | no | The maximum number of objects to return. |
|
filter |
query string |
string | A SCIM filter expression to filter the results with. |
The accepted filter fields are id and name.
| Name | Type | Description |
|
resources |
array | A list of ContactRoles objects. |
Create a Contact Role
Create a new ContactRole.
POST /scim/v2/contactRole
Parameters shown below:
| Name | Location | Type | Required | Description |
|
|
body |
ContactRole | yes | The ContactRole to create. |
Output Fields:
| Name | Type | Description |
|
resources |
ContactRole | A ContactRole object for the newly created ContactRole. |
Replace a Contact Role
Update a ContactRole by entirely replacing the existing ContactRole.
PUT /scim/v2/contactRole/{contactRoleId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
userID |
path |
string | yes | Unique identifier of the ContactRole to replace. |
|
|
body |
ContactRole | yes | The ContactRole to assign to the given ContactRoleId. |
Output Fields:
| Name | Type | Description |
|
|
ContactRole | A ContactRole object for the modified ContactRole. |
Group Type
Query SmartSense Group Types. A Group's GroupType defines the Group's place in the group hierarchy.
There are four GroupTypes defined in the SmartSense system:
- Account - The root of the hierarchy. There can only be one account level group per account.
- Organization - Organization-level groups are used as abstractions to logically divide the hierarchy. Organizations typically represent regions, divisions, states, or similar. Organizations can contain child organization groups under them. Organizations cannot contain Assets.
- Location - Location-level groups are used to define a physical location and hold Assets.
-
Department - Department-level groups are used to define subsections of a Location. Department-level groups must have a Location as their parent and can contain Assets. Departments cannot have any child groups.
Get All Group Types
Get all the available GroupTypes
GET /scim/v2/groupType
Parameters:
None.
Output Fields:
| Name | Type | Description |
|
key |
string | The GroupType's name. |
| Value | string | A description of the GroupType. |
Group Type Attribute
Create and Retrieve the Group Type Attributes configured for your Account. Groups in SmartSense can have Attributes defined for them. Different GroupTypes will have different required and non-required attributes depending on their assigned GroupTemplate. These Attributes are used for organization in the SmartSense application.
GroupTypeAttribute Object Model
| Name | Type | Mutability | Description |
| attributeID | string | ReadOnly | A unique identifier for the attribute. |
| attributeName | string | ReadOnly | The name of the Attribute that is displayed in the SmartSense application. |
| attributeType | string | ReadOnly | The name of the data type for the Attribute. |
| isRequired | boolean | ReadOnly |
A boolean indicating whether Groups of this type must provide a value for this Attribute. |
| groupType | string | ReadOnly |
The GroupType the Attribute belongs to. |
Get AllGroup Type Attributes
Get all the Attributes for all the GroupTypes in the system.
GET /scim/v2/groupTypeAttribute
Parameters:
None.
Output Fields:
| Name | Type | Description |
|
|
array | A list of GroupTypeAttributes for the account. |
Get Group Type Attributes for a Single GroupType
Get all the Attributes in the system for a single GroupType.
GET /scim/v2/groupTypeAttribute/{groupType}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
groupType |
path |
string | yes | The name of the GroupType to fetch attributes for. |
Output Fields:
| Name | Type | Description |
|
|
array | A list of GroupTypeAttributes for the given GroupType. |
Create a Group Type Attribute
Create a new Attribute for a GroupType.
POST /scim/v2/groupTypeAttribute
Parameters shown below:
| Name | Location | Type | Required | Description |
|
|
body |
GroupTypeAttribute | yes | The GroupTypeAttribute to Create. |
Output Fields:
| Name | Type | Description |
|
|
GroupTypeAttribute | A GroupTypeAttribute object for the newly created Attribute. |
Groups
The Groups endpoints are used to create, update, and delete Groups from the SmartSense system, as well as manage the Users associated with them. Groups in SmartSense are organized into a hierarchical tree by their GroupType. Groups are used to organize Assets, and Users are assigned to Groups with a ContactRole. The SCIM Group schema is defined by RFC 7643 Section 4.2.
Group Object Model
SmartSense uses all the attributes of the SCIM Group model and extends it.
| Name | Type | Mutability | Description |
| id | string | ReadOnly | A globally unique identifier for the group. |
| externalid | string | ReadWrite | An identifier provided by the client. This attribute is not used by the SmartSense application and is for external tracking only. |
| parentid | string | Immutable | The Id of the Group's Parent Group. |
| displayName | string | ReadWrite |
A name for the Group as displayed in the SmartSense application. |
| type | GroupType | Immutable |
The type of the Group. |
| attributes | array | ReadWrite |
A list of attributes associated with the Group. |
| members | array | ReadWrite |
A list of Users that belong to the Group. See Members. |
| meta | Meta | ReadOnly |
The meta info for the Group. |
Members Object Model
| Name | Type | Mutability | Description |
| valve | string | Immutable | The Id of the Member. It must be a valid UserId. |
| contactRoleId | string | Immutable | The ContactRoleId of for the Member of the Group. |
| type | string | Immutable | The type of the member object. |
| $ref | string | Immutable |
A URL reference that can be used to GET the member. |
Get One Group
Get a single Group identified by the given GroupId.
GET /scim/v2/groups/{groupId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
groupId |
path |
string | yes | Unique identifier of the requested Group. |
Output Fields:
| Name | Type | Description |
|
|
SCIM Group | A SCIM Group representation of the requested Group. |
Get All Groups
Gets all the Groups within the Account, one page at a time.
GET /scim/v2/groups
Parameters shown below:
| Name | Location | Type | Required | Description |
|
startIndex |
query string |
integer (32 bit) | no | 1-based index of where to start the page. Defaults to 1. |
|
count |
query string |
integer (32 bit) | no | The maximum number of objects to return. |
|
filter |
query string |
string | no | A SCIM filter expression to filter the results with. |
The accepted filter fields are id, externalId, displayname, and type.
Output Fields:
| Name | Type | Description |
|
resources |
array | A list of SCIM Groups objects. |
Create a Group
Create a new Group.
POST /scim/v2/groups
Parameters shown below:
| Name | Location | Type | Required | Description |
|
|
body |
SCIM Group | yes | The Group to create. |
Output Fields:
| Name | Type | Description |
|
|
SCIM Group | A SCIM Group representation of the newly created Group. |
Replace a Group
Update a Group by entirely replacing the existing Group.
PUT /scim/v2/groups/{groupId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
groupId |
path |
string | yes | Unique identifier of the Group to replace. |
|
|
body |
SCIM Group | yes | The Group to assign to the given GroupId. |
Output Fields:
| Name | Type | Description |
|
|
SCIM Group | A SCIM Group representation of the modified Group. |
Update a Group
Modify an existing Group in place.
PATCH /scim/v2/groups/{groupId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
groupId |
path |
string | yes | Unique identifier of the Group to modify. |
|
operations |
body |
array | yes | A list of SCIM PATCH operations. |
Output Fields:
HTTP 204 No Content
Remove a Group
Delete a Group from the System. This cannot be undone.
DELETE /scim/v2/groups/{groupId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
groupId |
path |
string | yes | Unique identifier of the Group to delete. |
Output Fields:
HTTP 204 No Content
Resource Type
Get the SCIM Resource Types for SmartSense's defined resources. SCIM Resource Types are defined and required by RFC 7643 Section 6.
ResourceType Object Model
| Name | Type | Mutability | Description |
| id | string | ReadOnly | An ID for the ResourceType. |
| name | string | ReadOnly | The name of the Resource. |
| description | string | ReadOnly | A description for the Resource. |
| endpoint | string | ReadOnly |
The primary endpoint to retrieve resources of this ResourceType. |
| schema | string | ReadOnly |
The ResourceTypes base schema. |
| schemaExtension | SchemaExtension | ReadOnly |
A list of schemas that extend the base schema for the ResourceType. |
| meta | Meta | ReadOnly |
The meta info for the ResourceType. |
SchemaExtension Object Model
| Name | Type | Mutability | Description |
| schema | string | ReadOnly | The schema extension that is being applied. |
| required | boolean | ReadOnly | Whether applying the extension is required when interacting with the system. |
Get One Resource Type
Get the Resource definition for the Resource identified by the given name.
GET /scim/v2/resourceType/{resourceName}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
resourceName |
path |
string | yes | The name of the Resource to fetch. |
Output Fields:
| Name | Type | Description |
|
|
ResourceType | The resource definition for the given Resource name. |
Get All Resource Types
Get all the ResourceTypes in the system.
GET /scim/v2/resourceType
Parameters:
None.
Output Fields:
| Name | Type | Description |
|
|
array | A list of ResourceTypes in the system. |
Schema
Get the documented SmartSense SCIM schemas. SCIM schemas are defined by RFC 7643 Section 7.
Get One Schema
Get a single SCIM Schema definition by the given Schema ID.
GET /scim/v2/schema/{schemaId}
| Name | Location | Type | Required | Description |
|
schemaId |
path |
string | yes | A unique URI for the Schema. |
Output Fields:
| Name | Type | Description |
|
|
Schema | A Schema definition as defined by RFC 7643 Section 7. |
Get All the Schemas
Get all the SCIM Schemas defined by the system.
GET /scim/v2/schema
Parameters:
None.
Output Fields:
| Name | Type | Description |
|
resources |
array | A list of Schema objects. |
Service Provider Configuration
Gets the SmartSense SCIM Service Provider Configuration. The SCIM service provider configuration is defined and required by RFC 7643 Section 5.
Get the Configuration
Get our Service Provider Configuration as defined by the SCIM specification.
GET /scim/v2/servicesProviderConfiguration
Parameters:
None.
Output Fields:
| Name | Type | Description |
|
|
ServiceProviderConfig | A SCIM ServiceProviderConfig for this SCIM Service. |
Users
The Users endpoints are used to create, update, and delete Users from the SmartSense system. SmartSense Users created through the SCIM API can only log in to the SmartSense system through a SAML SSO integration. SmartSense only uses a subset of the available SCIM User attributes. The full SCIM User schema is defined by RFC 7643 Section 4.1.
User Object Model
| Name | Type | Mutability | Description |
| id | string | ReadOnly | A globally unique identifier of the User. |
| externalid | string | ReadWrite | An identifier provided by the client. This attribute is not used by the SmartSense application and is for external tracking only. |
| username | string | Immutable | A unique string identifier of the user. |
| active | boolean | ReadWrite |
A boolean marking if the user is allowed to access the system. |
| userType | AccessRole | ReadWrite |
A string identifying the User's permissions in the system. |
| name | Name | ReadWrite |
A complex object containing the User's first and last names. |
| smartSenseEnterpriseUser | smartSenseEnterpriseUser | ReadWrite |
A complex attribute holding SmartSense's SCIM extension attributes. |
| emails | array | ReadWrite |
A list of Emails. SmartSense only accepts and returns one email in this list. |
| phoneNumbers | array | ReadWrite |
A list of PhoneNumbers. SmartSense accepts two types of phone numbers: SMS and voice. |
| groups | array | ReadOnly |
A list of Groups the User belongs to. |
| meta | Meta | ReadOnly |
The meta info for the User. |
Get One User
Get a single User identified by the given UserId.
GET /scim/v2/users/{userId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
userId |
path |
string | yes | Unique identifier of the requested User. |
Output Fields:
| Name | Type | Description |
|
|
SCIM User | A SCIM User representation of the requested user. |
Get All Users
Gets all the Users within the Account, one page at a time.
GET /scim/v2/users
Parameters shown below:
| Name | Location | Type | Required | Description |
|
startIndex |
query string |
integer (32 bit) | no | 1-based index of where to start the page. Defaults to 1. |
|
count |
query string |
integer (32 bit) | no | The maximum number of objects to return. |
|
filter |
query string |
string | no | A SCIM filter expression to filter the results with. |
The accepted filter fields are id, externalId, username, name.familyName, and name.givenName.
Output Fields:
| Name | Type | Description |
|
resources |
array | A list of SCIM Users objects. |
Create a User
Create a new User.
POST /scim/v2/users
Parameters shown below:
| Name | Location | Type | Required | Description |
|
|
body |
SCIM User | yes | The user to create. |
Output Fields:
| Name | Type | Description |
|
|
SCIM User | A SCIM User representation of the newly created User. |
Replace a User
Update a User by entirely replacing the existing User.
PUT /scim/v2/users/{userId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
userId |
path |
string | yes | Unique identifier of the User to be replaced. |
|
|
body |
SCIM User | yes | The User to assign to the given UserId. |
Output Fields:
| Name | Type | Description |
|
|
SCIM User | A SCIM User representation of the modified user. |
Update a User
Modify an existing User in place.
PATCH /scim/v2/users/{userId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
userId |
path |
string | yes | Unique identifier of the User to be modified. |
|
operations |
body |
array | yes | A list of SCIM PATCH operations. |
Output Fields:
HTTP 204 No Content
Remove a User
Delete a User from the System. This cannot be undone. For a reversible delete action see the "active" field of the SCIM User.
DELETE /scim/v2/users/{userId}
Parameters shown below:
| Name | Location | Type | Required | Description |
|
userId |
path |
string | yes | Unique identifier of the User to delete. |
Output Fields:
HTTP 204 No Content