Skip to main content

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

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

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

id

Omit

The server assigns it.

externalID

Optional

Your id for the user. SmartSense does not use it in the product.

userName

Required

Must be unique in the account. userName is immutable after create.

name.givenName

Required

The user's first name.

name.familyName

Required

The user's last name.

emails

Required

Send at least one value. The API stores the entry with primary true, or the first entry if none is primary. The response returns one email, with type work and primary true.

active

Optional

Leave it out and the user is stored as active. false disables the user. true enables the user.

userType

Optional

Leave it out and the API stores Viewer. Unknown values are stored as Viewer. See User type.

phoneNumbers

Optional

Leave it out when the user has no numbers. See Phone numbers.

groups

Ignored

Returned on read. To change membership, use the Groups API.

smartSenseEnterpriseUser

Do not send

Leave it out.

meta

Ignored

Returned on read. See Meta.

password

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

id

Ignored

The id in the URL is used.

externalID

Optional

Leave it out and the stored value is cleared. Your id for the user. SmartSense does not use it in the product.

userName

Required

The field must be in the body. The stored value does not change.

name.givenName

Required

The user's first name.

name.familyName

Required

The user's last name.

emails

Required

Send at least one value. The API stores the entry with primary true, or the first entry if none is primary. The response returns one email, with type work and primary true.

active

Optional

Leave it out and the user is stored as active. false disables the user. true enables the user.

userType

Optional

Leave it out and the API stores Viewer. Unknown values are stored as Viewer. See User type.

phoneNumbers

Optional

Leave it out and the stored voice number, SMS number, and extension are cleared. See Phone numbers.

groups

Ignored

Returned on read. To change membership, use the Groups API.

smartSenseEnterpriseUser

Do not send

Leaving it out clears the user's default contact role.

meta

Ignored

Returned on read.

password

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

id

Ignored

The id in the URL is used.

externalID

Optional

Leave it out and the stored value stays. Your id for the user. SmartSense does not use it in the product.

userName

Immutable

The stored value does not change. An empty value fails the request.

name.givenName

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.

name.familyName

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.

emails

Can be replaced

Send at least one value to replace the stored email. An empty value fails the request. Leave it out and the stored email stays. The API stores the entry with primary true, or the first entry if none is primary.

active

Optional

Leave it out and the stored value stays. false disables the user. true enables the user.

userType

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.

phoneNumbers

Optional

Leave it out and the stored numbers stay. See Phone numbers.

groups

Ignored

Returned on read. To change membership, use the Groups API.

smartSenseEnterpriseUser

Do not send

Leave it out.

meta

Ignored

Returned on read.

password

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.

  • voice or work is the voice number.

  • sms or mobile is the SMS number.

  • The API stores one voice number and one SMS number. If several entries match a kind, it keeps the one with primary true, otherwise the first.

  • extension is stored for the voice number.

  • Send E.164 when you can, for example +12025551234. A value that starts with tel: 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 type other than voice, work, sms, or mobile is ignored. That number is not stored and the request still succeeds.

  • On replace, omit phoneNumbers only 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

Viewer

Stored. This is the default when userType is omitted on create or replace.

Super Administrator

Stored. Unrestricted access.

Responder

Stored. Can respond to incidents and checklists.

Responder +

Stored. Responder, and can place assets in or out of maintenance mode.

Api User

Deprecated. The API still stores this value, and this user cannot sign in to SmartSense.

Administrator

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

id

Omit

The server assigns it.

displayName

Required

The name shown in SmartSense.

parentID

Required

It must be an existing group id. See Group type for which parent types are allowed. parentID is immutable after create.

type

Required

Account, Organization, Location, or Department. You cannot create a group of type Account. Send the capitalization in the Group type table. type is immutable after create.

attributes

Required

The array may be empty. Each entry has type for the attribute name and value for the attribute value. Include every required key for that group type. Unknown names are rejected. Read the names for the account from GET /scim/v2/GroupTypeAttribute.

members

Optional

See Members.

externalID

Optional

Your id for the group. SmartSense does not use it in the product.

meta

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

id

Ignored

The id in the URL is used.

displayName

Required

The name shown in SmartSense.

parentID

Ignored

parentID is immutable. The stored parent does not change.

type

Ignored

type is immutable. The stored type does not change.

attributes

Optional

Leave attributes out and the stored attributes stay. If you send the array, include every required key for that group type. Unknown names are rejected.

members

Required

The array may be empty. An empty array removes every member. See Members.

externalID

Optional

Leave it out and the stored value is cleared. SmartSense does not use it in the product.

meta

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

id

Ignored

The id in the URL is used.

displayName

Optional

Leave it out and the stored name stays.

parentID

Do not change

parentID is immutable. The patch fails if the value would change.

type

Do not change

type is immutable. The patch fails if the value would change.

attributes

Optional

Leave attributes out and the stored attributes stay. Patch does not enforce required keys. Unknown names are rejected.

members

Optional

Leave members out and the stored members stay. Send a list to replace them. An empty list removes every member. See Members.

externalID

Optional

Leave it out and the stored value stays. SmartSense does not use it in the product.

meta

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

Organization

Account or Organization

Location

Account or Organization

Department

Location

Account

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

value

Required

The user id from the Users API. A user name is not accepted. The user must already exist.

contactRoleId

Optional

A contact role id that already exists on the account. Read the ids from GET /scim/v2/ContactRole. Send this name. contactRoleIDs is ignored, and the fallback below runs.

type

Ignored on write

The response uses a membership label.

$ref

Ignored on write

The response returns a URL for the user.

When contactRoleId is omitted, the API chooses one in this order.

  1. The user's default contact role, if that user has one.

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

id

Omit on create

The server assigns it. The id in the URL is used on replace.

name

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

attributeId

Returned

The server assigns it.

attributeName

Returned

Send this as name. Required.

attributeType

Returned

Required. The only accepted value is string.

isRequired

Returned

Optional. Leave it out and the attribute is not required.

groupType

Returned

Required. Account, Organization, Location, or Department.

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

resourceType

The name of the resource, such as User or Group.

location

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

id

The resource type id.

name

The name of the resource.

description

A description of the resource.

endpoint

The path used to read resources of this type.

schema

The base schema for the resource type.

schemaExtensions

Extensions of the base schema. Each entry has schema and required.

meta

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

Did this answer your question?