SCIM API

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:

1. A Core Schema (RFC7643) controlling how the data is modelled.
2. 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

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

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.

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.