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 (now deprecated and no longer required, but remains current for backward compatibility) 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.

Email

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."

Note: Accepted Phone Number Formats:

- E.164: `+11234567890`
- RFC3966: `tel:+11234567890` or `tel:+1-123-456-7890`
- *International Format: `+1(123)456-7890,` `+1-123-456-7890,` `+1.123.456.7890,` or`1 123 456 7890`
- National Format:`123-456-7890,` `123.456.7890,` `(123)456-7890,` or `123 456 7890

*If an international number follows the same format as a national number, it will be saved as a US number prefixed with `+1`

Regardless of the input format, SmartSense stores all phone numbers in E.164 format and returns them as `+11234567890.`
Invalid phone number formats will not be saved.

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.

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.

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.

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.

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.
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.