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.
To ease the managing of SmartSense users, SmartSense provides a set of endpoints that conform to the SCIM version 2 standard.
The production base URL is:
https://api.smartsense.co/scim/v2
SmartSense users created through this API can sign in to SmartSense only through a SAML SSO integration. The API never accepts or returns a password.
Results paging
Per SCIM RFC 7644, a list endpoint includes paging fields in the response.
Name | Type | Description |
totalResults | integer | The total number of results matching the query. |
startIndex | integer | The 1-based index of the first result in the current page. |
itemsPerPage | integer | The number of results returned in the current page. |
List responses for users, groups, and contact roles include these fields.
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 | 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 | 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 | ReadOnly | A list of schemas that extend the base schema for the ResourceType. | |
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
Create is POST /scim/v2/Users. Replace is PUT /scim/v2/Users/{id}. Patch is PATCH /scim/v2/Users/{id}. Delete is DELETE /scim/v2/Users/{id}. Create and replace use the same required fields. The stored user name does not change on replace or patch. Delete returns no body.
SmartSense uses a subset of the SCIM user attributes in RFC 7643. The names below are the names the API reads and writes.
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 | 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 | ReadOnly | The meta info for the User. |
Create a user
The response returns the user.
Attribute | What to send | Notes |
| Omit | The server assigns it. |
| Optional | Your id for the user. SmartSense does not use it in the product. |
| Required | Must be unique in the account. |
| Required | The user's first name. |
| Required | The user's last name. |
| Required | Send at least one |
| Optional | Leave it out and the user is stored as active. |
| Optional | Leave it out and the API stores Viewer. Unknown values are stored as Viewer. See User type. |
| Optional | Leave it out when the user has no numbers. See Phone numbers. |
| Ignored | Returned on read. To change membership, use the Groups API. |
| Do not send | Leave it out. |
| Ignored | Returned on read. See Meta. |
| Do not send | The API never returns a password. |
Replace a user
Replace writes the mapped fields from the body you send. When a row says leaving a field out clears it or stores a default, that applies to this call. The response returns the user.
Attribute | What to send | Notes |
| Ignored | The id in the URL is used. |
| Optional | Leave it out and the stored value is cleared. Your id for the user. SmartSense does not use it in the product. |
| Required | The field must be in the body. The stored value does not change. |
| Required | The user's first name. |
| Required | The user's last name. |
| Required | Send at least one |
| Optional | Leave it out and the user is stored as active. |
| Optional | Leave it out and the API stores Viewer. Unknown values are stored as Viewer. See User type. |
| Optional | Leave it out and the stored voice number, SMS number, and extension are cleared. See Phone numbers. |
| Ignored | Returned on read. To change membership, use the Groups API. |
| Do not send | Leaving it out clears the user's default contact role. |
| Ignored | Returned on read. |
| Do not send | The API never returns a password. |
Patch a user
Patch changes only the fields in the patch. Leave a field out to keep its stored value. You can replace a required field with a new value. An empty value fails the request. Patch returns no body.
Attribute | What to send | Notes |
| Ignored | The id in the URL is used. |
| Optional | Leave it out and the stored value stays. Your id for the user. SmartSense does not use it in the product. |
| Immutable | The stored value does not change. An empty value fails the request. |
| Can be replaced | Send a new first name to replace the stored one. An empty value fails the request. Leave it out and the stored name stays. |
| Can be replaced | Send a new last name to replace the stored one. An empty value fails the request. Leave it out and the stored name stays. |
| Can be replaced | Send at least one |
| Optional | Leave it out and the stored value stays. |
| Optional | Leave it out and the stored access level stays, unless that level is one the API does not allow. Those are rewritten to Viewer. Unknown values are stored as Viewer. See User type. |
| Optional | Leave it out and the stored numbers stay. See Phone numbers. |
| Ignored | Returned on read. To change membership, use the Groups API. |
| Do not send | Leave it out. |
| Ignored | Returned on read. |
| Do not send | The API never returns a password. |
Phone numbers
You may omit phoneNumbers. A user can have one voice number and one SMS number. When you send a number, type is required. A number with no type fails the request.
voiceorworkis the voice number.smsormobileis the SMS number.The API stores one voice number and one SMS number. If several entries match a kind, it keeps the one with
primarytrue, otherwise the first.extensionis stored for the voice number.Send E.164 when you can, for example
+12025551234. A value that starts withtel:is accepted. A number with no leading+is parsed as a US number.The API stores the number in E.164 and returns it that way.
A number the API cannot parse is rejected. The request fails. The number is not dropped silently.
A
typeother thanvoice,work,sms, ormobileis ignored. That number is not stored and the request still succeeds.On replace, omit
phoneNumbersonly when you want the stored numbers removed. On patch, leave the field out when you want the stored numbers kept.
User type
userType is the SmartSense access level. Matching ignores case and spaces. GET /scim/v2/AccessRole returns the levels enabled for the account.
userType | What the API does |
| Stored. This is the default when |
| Stored. Unrestricted access. |
| Stored. Can respond to incidents and checklists. |
| Stored. Responder, and can place assets in or out of maintenance mode. |
| Deprecated. The API still stores this value, and this user cannot sign in to SmartSense. |
| Stored only when the account allows the group admin role. Otherwise stored as Viewer. This is the limited admin for the user's locations, not Super Administrator. |
Any other value | Stored as Viewer. The API does not return an error. This includes Editor, Sensor Alerts Editor, Installer, Group Viewer, Group Responder, and Checklist User. |
Send Super Administrator for a full administrator. The value Administrator is the limited group admin role.
On create and on replace, an omitted userType is stored as Viewer. On patch, the stored access level stays unless the patch changes userType. A patch still rewrites an access level the API does not allow, even when userType is not in the patch.
Minimal user body
POST /scim/v2/Users
{
"userName": "[email protected]",
"name": {
"givenName": "Ada",
"familyName": "Lovelace"
},
"emails": [
{
"value": "[email protected]",
"primary": true
}
]
}
This is a complete create. active defaults to true, and userType defaults to Viewer.
Groups
How RFC 7643 defines a group
A group is a named list of members. The required field is displayName. The specification allows membership to express access, and it leaves that meaning to the application. Roles and entitlements are attributes of the user.
What a group means in SmartSense
A group is a place in the account: an Organization, a Location, or a Department. Groups organize assets. Who is notified for that place is a contact role on the member. A person's access level is userType. Create also requires parentID, type, and attributes. parentID must be a group that already exists in SmartSense, so the locations need to exist before people are assigned to them. Use replace or patch to keep membership current when a location assignment changes.
What an identity provider usually sends
An identity provider sends a directory group: the group name and its members. Okta Group Push sends displayName and members. Microsoft Entra provisions a group object the same way, and sends application roles separately on the user, in roles. A request that sends only a name and members fails on this API.
Create is POST /scim/v2/Groups. Replace is PUT /scim/v2/Groups/{id}. Patch is PATCH /scim/v2/Groups/{id}. Delete is DELETE /scim/v2/Groups/{id}. Create and replace do not use the same required fields. Delete returns no body.
Create a group
The response returns the group.
Attribute | What to send | Notes |
| Omit | The server assigns it. |
| Required | The name shown in SmartSense. |
| Required | It must be an existing group id. See Group type for which parent types are allowed. |
| Required |
|
| Required | The array may be empty. Each entry has |
| Optional | See Members. |
| Optional | Your id for the group. SmartSense does not use it in the product. |
| Ignored | Returned on read. |
Replace a group
type and parentID in the body are ignored. The response returns the group.
Attribute | What to send | Notes |
| Ignored | The id in the URL is used. |
| Required | The name shown in SmartSense. |
| Ignored |
|
| Ignored |
|
| Optional | Leave |
| Required | The array may be empty. An empty array removes every member. See Members. |
| Optional | Leave it out and the stored value is cleared. SmartSense does not use it in the product. |
| Ignored | Returned on read. |
Patch a group
Patch can change displayName, externalID, attributes, and members. Leave a field out of the patch to keep its stored value. Patch returns no body.
Attribute | What to send | Notes |
| Ignored | The id in the URL is used. |
| Optional | Leave it out and the stored name stays. |
| Do not change |
|
| Do not change |
|
| Optional | Leave |
| Optional | Leave |
| Optional | Leave it out and the stored value stays. SmartSense does not use it in the product. |
| Ignored | Returned on read. |
Group type
The type you send has to be a child of the parent you send. The API rejects any other pairing. Send the type with the capitalization in the table. location is not the same as Location.
type | Allowed parent type |
|
|
|
|
|
|
| You cannot create this type. It is the root group for the account. |
After create, type and parentID do not change. Replace ignores both fields. Patch fails if either field would change.
Minimal group body
POST /scim/v2/Groups
{
"displayName": "North store",
"type": "Location",
"parentID": "<parent group id>",
"attributes": []
}
Add members only when you want users on the group at create time. attributes must be present. Use an empty array when that group type has no required attributes. Replace [] with the required type and value pairs for the account.
Members
Send members on the group, not on the user. Each entry is one user and one contact role. A contact role, also called a location role, decides who is notified for that group. userType is the person's access level. The same user may appear more than once with different contact roles.
Attribute | When a member is sent | Notes |
| Required | The user |
| Optional | A contact role id that already exists on the account. Read the ids from |
| Ignored on write | The response uses a membership label. |
| Ignored on write | The response returns a URL for the user. |
When contactRoleId is omitted, the API chooses one in this order.
The user's default contact role, if that user has one.
Otherwise the account default contact role. The API creates that default role if the account does not have one yet.
A contactRoleId that does not exist on the account is rejected.
{
"value": "<user id>",
"contactRoleId": "<contact role id>"
}Contact roles
A contact role decides who is notified when an asset in a group enters an alarm state. Assign it on a group member with contactRoleId. You can omit contactRoleId. The fallback order is in Members.
List is GET /scim/v2/ContactRole. Read one is GET /scim/v2/ContactRole/{id}. Create is POST /scim/v2/ContactRole. Replace is PUT /scim/v2/ContactRole/{id}.
Attribute | What to send | Notes |
| Omit on create | The server assigns it. The id in the URL is used on replace. |
| Required | The name shown in SmartSense. It can be at most 50 characters, and it must be unique on the account. Replace can change it. |
Group type attributes
Groups can have attributes that depend on the account and the group type. Read them before you create a group, and include every attribute with isRequired true.
List every attribute with GET /scim/v2/GroupTypeAttribute. List one group type with GET /scim/v2/GroupTypeAttribute/{groupType}. Create one with POST /scim/v2/GroupTypeAttribute.
Attribute | On a read | On create |
| Returned | The server assigns it. |
| Returned | Send this as |
| Returned | Required. The only accepted value is |
| Returned | Optional. Leave it out and the attribute is not required. |
| Returned | Required. |
On group create, an attribute with isRequired true must be present in attributes. If that list is empty, send "attributes": [].
Meta
Read responses include meta. You do not send it on create, replace, or patch.
Attribute | Description |
| The name of the resource, such as User or Group. |
| A URL that can be used to read the object. |
Resource types
List is GET /scim/v2/ResourceType. Read one is GET /scim/v2/ResourceType/{name}. These endpoints are read only. RFC 7643 requires a service provider to publish its resource types.
Attribute | Description |
| The resource type id. |
| The name of the resource. |
| A description of the resource. |
| The path used to read resources of this type. |
| The base schema for the resource type. |
| Extensions of the base schema. Each entry has |
| See Meta. |
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