What is SCIM?
SCIM stands for “System for Cross-domain Identity Management". It's a standardized way of representing users, groups, and anything else related. SCIM helps to standardize methods for acting on this data, such as creating, querying, searching, updating and deleting. In other words, it’s an API model.
These two parts of SCIM are split into two standards:
- A Core Schema (RFC7643) controlling how the data is modelled.
- A Protocol for interacting with the data (RFC7644). (Learn More)
What is SCIM used for?
SCIM is used by Single Sign-On (SSO) services and identity providers to manage people across a variety of tools, including Reward Gateway, and is an API for managing the employee data of clients. It provides an easy way for our clients to manage new hires and leavers from their business, ensuring they have the right access to the program at the right times – e.g. new hires will be added once joined and leavers will be removed once they leave. This will work automatically via the SCIM integration and will require no additional input from HR.
What SCIM versions are supported?
Reward Gateway currently supports SCIM version 1.1 and SCIM version 2.0.
Accessing the SCIM API
All SCIM methods are accessed over the HTTP protocol. Being a REST API, the HTTP Verbs (e.g. GET, POST, PUT, PATCH and DELETE) used to access each method are extremely important.
-
GET – Retrieve Information about a User or Users.
-
POST – Create a new user.
-
PUT / PATCH – Modify a user.
-
DELETE – Remove a user.
The base URL for all SCIM API calls are unique for each Reward Gateway Client. This URL can be obtained through the Reward Gateway Integration Dashboard. All SCIM methods are branches of this base URL.
https://api.rewardgateway.net/{programme_guid}/scim/{version}/
An OAuth Bearer Token is required to access the SCIM API.
The OAuth Bearer token can be generated when enabling the SCIM API for the client through the Integration Dashboard. The OAuth Bearer Tokens can also be revoked or rotated through the same dashboard at any time.
The generated OAuth Bearer Token must be included via an Authorization with a type of Bearer when calling any SCIM API methods.
Provide a JSON request body for POST, PUT, and PATCH write operations and set your HTTP Content-type header to application/json.
An example SCIM API call would like this:
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
Bearer Token Expiration
We have added a new 'Expiry date' field to all Scim API integrations to let clients know when the Bearer token will expire.
New email alerts will also go out to IT Administrators (and to Account Managers if there are no IT administrators for a client) to remind them that their Bearer token will expire soon. Those alerts will be generated when there're 14, 7 and 3 days left until the expiration of the token.
SCIM API Endpoints
Service Provider Configurations
GET /ServiceProviderConfigs
Returns Reward Gateway’s configuration details for the client platform SCIM API. This includes which operations are supported. (Learn More)
Example Request:
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/ServiceProviderConfigs HTTP/1.1 Host: api.rewardgateway.net Accept: application/json
Schemas
GET/Schemas/Users
Reward Gateway currently supports schemas for Users. Querying the schemas will provide the most up to date rendering of the supported SCIM attributes. We do not currently support schemas for Groups.
Example Request:
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Schemas/User HTTP/1.1 Host: api.rewardgateway.net Accept: application/json
Users
Attributes are the information associated with a user's account. This is information that someone would typically set in their profile.
The following tables map SCIM attributes to the profile fields. Most of these profile fields are exposed directly in Reward Manager to be amended or in the My Account section of the programme where the member can edit it. Sometimes, multiple SCIM attributes map to a single profile field – for example, externalId field and userName field both map to a single unique identifier on Reward Gateway.
SCIM Attribute Mapping
|
Profile Field |
SCIM Field |
Description |
Attribute Type |
Required |
Read Only |
|
Member ID (UUID) |
id |
Unique Identifier associated to a user on Reward Gateway |
Singular |
True |
True |
|
Membership No (Payroll Number, Employee Number) |
userName |
Unique Identifier associated to a user on the Identity Provider |
Singular |
True |
False |
|
Membership No (Payroll Number, Employee Number) |
externalId |
Unique Identifier associated to a user on the Identity Provider |
Singular |
False |
False |
|
Password |
password |
Password for the user |
Singular |
False |
False |
|
First Name |
name.givenName |
User’s First Name |
Singular |
True |
False |
|
Last Name |
name.familyName |
User’s Last Name |
Singular |
True |
False |
|
Email Address |
emails[0][‘value’] |
User’s Email Address associated with the account |
Multi-Valued |
True |
False |
|
License Country |
locale |
The locale* of the member |
Singular |
False |
False |
|
Eligibility Status |
active |
Eligibility status of the member. If passed as false will begin the account shut-down process. |
Singular |
False |
False |
|
Cost Center |
enterprise.costCenter |
Cost Center associated with the member |
Singular |
False |
False |
|
Organization |
enterprise.organization |
Organization associated with the member |
Singular |
False |
False |
|
Division |
enterprise.division |
Division associated with the member |
Singular |
False |
False |
|
Department |
enterprise.department |
Department associated with the member |
Singular |
False |
False |
|
Line Manager ID |
enterprise.manager.managerId |
Line Manager of the member |
Singular |
False |
False |
* The locale is specified in the format “en_[CountryCode]“, where CountryCode follows the two letter ISO 3166-1 alpha 2 standard. (e.g. Italy is represented as the en_IT locale)
GET/Users
Returns a paginated list of users, ten users per page by default. To be able to paginate through the list of users please use the startIndex and count query parameters.
It's also possible to return a list of specific types of users through filtering. Learn more about filtering below.
Filters
It's possible to filter the list of users returned through the SCIM API using any of the SCIM attributes mentioned in the SCIM Attribute mapping section. The SCIM API will evaluate the conditions and return a set of user matching the criteria.
The following rules apply:
-
The filter parameter must contain one valid boolean operator.
-
Each expression must contain an attribute name followed by an attribute operator.
-
Multiple expressions may be combined using two logical operators.
-
Expressions can be grouped together using "( )".
-
Expressions must be evaluated using the standard order of operations.
-
String literals must be valid JSON strings The following is a list of valid operators.
|
Operator |
Description |
|
eq |
Equal |
|
co |
Contains |
|
sw |
Starts with |
|
ew |
Ends with |
|
gt |
Greater than |
|
ge |
Greater than or Equal |
|
lt |
Less than |
|
le |
Less than or Equal |
|
and |
Logical And |
|
or |
Logical Or |
Examples Requests:
Paginating (Finding the first 50 users)
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?startIndex=1&count=50 HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
Paginating (Finding the second set of 50 users)
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?startIndex=50&count=50 HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
Searching users with userName
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=userName eq "jane.doe@example.com" HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
Searching users with either userName or familyName
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=userName eq "jane.doe@example.com" OR familyName eq "Doe" HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
Searching users with names like
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=givenName co "ja" HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
GET/Users/{id}
Returns a single user resource. The value of the {id} must be the user's corresponding Member ID (UUID) in Reward Gateway.
Example Request:
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/9a12e6b3-c06d-6d18-98d7-gf249d89a4e7 HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
POST/Users
Creates a new user on the client programme. Must include all required fields mentioned in the SCIM API Attributes Mapping section.
Example Request:
POST /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users HTTP/1.1
Host: api.rewardgateway.net
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"name": {
"givenName": "Jane",
"familyName": "Doe"
},
"emails": [{
"primary": true,
"value": "jane.doe@example.com",
"type": "work"
}],
"externalId": "K17651323",
"active": true,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"costCenter": "Cost Center A",
"organization": "Organization A",
"division": "Division A",
"department": "Department A",
"manager": {
"managerId": "K18762212"
}
}
}
PATCH/USERS/{id}
Updates an existing user resource, overwriting values for specified attributes.
Attributes that are not provided will remain unchanged. Disabled users can be re-enabled by sending active attribute equal to true. The value of the {id} should be the user's corresponding Reward Gateway Member ID (UUID).
Example Request:
PATCH /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/9a12e6b3-c06d-6d18-98d7-gf249d89a4e7 HTTP/1.1
Host: api.rewardgateway.net
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"name": {
"givenName": "Jane",
"familyName": "Smith"
},
"active": true
}
PUT/USERS/{ID}
Updates an existing user resource, overwriting all values for a user even if an attribute is empty or not provided. All required attributes must be passed to this method.
If an attribute that had been set previously is left blank during a PUT operation, the new value will be blank in accordance with the data type of the attribute. Deactivated users can be re-enabled by setting the active attribute to true. The value of the {id} should be the user's corresponding Reward Gateway Member ID (UUID).
Example Request:
PUT /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/9a12e6b3-c06d-6d18-98d7-gf249d89a4e7 HTTP/1.1
Host: api.rewardgateway.net
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"name": {
"givenName": "Jane",
"familyName": "Smith"
},
"emails": [{
"primary": true,
"value": "jane.doe@example.com",
"type": "work"
}],
"externalId": "K17651323",
"active": true,
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"costCenter": "Cost Center A",
"organization": "Organization A",
"manager": {
"managerId": "K18762212"
}
}
}
The above request will remove associated Division and Department information as it is missing from the PUT request.
The password attribute is not supported for PUT and PATCH requests and sending it will result in an error.
DELETE/USERS/{ID}
Marks the user as deleted. The users shut down process will begin from the point the request is sent. This is the same as using PATCH or PUT methods and setting the active attribute to false.
Example Request:
DELETE /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/9a12e6b3-c06d-6d18-98d7-gf249d89a4e7 HTTP/1.1 Host: api.rewardgateway.net Accept: application/json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5N
Errors
Occasionally, our SCIM API will result in an error instead of the result you're expecting. This could be due to various reasons and Reward Gateway will make every attempt to respond with a descriptive error message that will help you figure out what went wrong and how to fix it. So make sure to look out for details in the error messages.
| Error | HTTP Response Code | Description |
| not_found | 404 | Invalid endpoint or SCIM method. |
| resource_not_found | 400 | Resource you're looking for could not be found. |
| no_user_found | 404 | User you're looking for could not be found. |
| user_exists | 409 | User you are trying to provision/add already exists. Please check the userName/externalId or the Email address of the user. |
| forbidden | 403 | You don't have the necessary scopes to access the SCIM API. |
| validation_error | 400 | The SCIM Schema passed is not valid. Look for details. |
| programme_invalid | 400 | For your SCIM API to work, your Reward Gateway program must be set up in a specific way. If this is the error you're facing, please contact your Client Success Manager or your Implementation Specialist. |
| filter_error | 400 | The filter request is invalid. Look for details. |
Membership Update History (Logs)
Please, note that SCIM updates will not appear under Members > Membership Update History in Reward Manager.
SCIM is different from SFTP or processing a membership file manually. Provisioning of an account via SCIM happens in real time and updating of account details happens in real time as well.
Since for a single account in a given day, there can be multiple SCIM attempts, we are not able to store a log for every single attempt.
The system you are using to configure SCIM (MS Azure/Okta/Ping) should already have an audit trail on their side where you can see how many member provision attempts happened and how many were successful.