SmartSense 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 (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. |
| 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. |
Interactive API Documentation
For detailed endpoint documentation and the ability to test API calls directly, visit our Swagger documentation:
The Swagger interface provides:
- Request and response schemas
- Interactive API testing