Overview of 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.
SCIM is defined by two separate standards:
- Core Schema (RFC7643) defines how the data is modelled.
- Protocol (RFC7644) defines how to interact with the data.
For more information, you can visit the SCIM website.
The Purpose of SCIM
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 time, 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.
Supported SCIM Versions
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 is 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 are 14, seven, and three 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. To learn more, you can read the Service Provider Configuration Schema on the datatracker website.
Example Request:
GET /8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/ServiceProviderConfigs HTTP/1.1
Host: api.rewardgateway.net
Accept: application/jsonSchemas
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/jsonUsers
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 by 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.
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 users 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 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5NGET/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 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImExYjk5NPOST/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. Users that have had their accounts disabled can have their accounts 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 user's shutdown 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. You can read the error messages for more details.
| 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)
SCIM updates will not appear under Members > Membership Update History in Reward Manager. Unlike SFTP or manually processing a membership file, SCIM provisioning and updates occur in real time. This means that when an account is provisioned or its details are updated via SCIM, the changes take effect immediately.
Because there can be multiple SCIM attempts for the same account within a single day, we are not able to store a log of every attempt in Reward Manager. Instead, you can refer to the audit trail provided by your SCIM configuration system (e.g. Microsoft Azure, Okta, Ping), which records how many provisioning attempts occurred and whether they were successful.
Comments
0 comments
Please sign in to leave a comment.