NAV Navbar

Introduction

đź‘Ź Welcome to the Reward Gateway Developer Portal đź‘Ź

The Reward Gateway Developer Portal provides a single source of truth for all developers to locate, access and consume services within Reward Gateway.

Authentication

All Reward Gateway APIs implement OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:

  1. Acquire an access token, and a refresh token
  2. Use the access token to make authenticated requests
  3. If you were issued a refresh token: refresh the access token when it expires

Before you begin, you will need to create a client. You can do this by accessing the Integration Dashboard on Reward Manager and selecting the REST API option.

Obtaining an access token

Obtaining an access token is a three-step process (3-legged oAuth):

  1. Redirect the user to Reward Gateway Identity to authorise your app
  2. Reward Gateway Identity redirects the user back to your app with an authorization code
  3. Exchange the authorization code for an access token.

Redirect the user to Reward Gateway Identity

Send the user to Reward Gateway Identity in a web browser, where they will log in and grant access to their account.

Parameter Required Description
client_id true Your client ID.
redirect_uri true A URI to which users will be redirected after authorising your app.
response_type true Must be set to code
state false An unguessable random string used to protect against cross-site request forgery attacks.

Reward Gateway Identity redirects the user

Example redirect url

https://identity.rewardgateway.net/?
    client_id=$client_id&
    redirect_uri=$redirect_uri&
    response_type=code&
    state=$state_token

Example callback

https://example.com/oauth/callback?
    code=$authorization_code&
    state=$state_token

If the user allows access to their account, Reward Gateway Identity redirects them back to your app.

Parameter Description
code A temporary authorization code which will be exchanged for an access token in the next step.
state The same string you provided as state when sending the user to Reward Gateway Identity. If this value differs from what you sent, you must abort the authentication process.

Exchange the authorization code

Example request

http --form POST "https://identity.rewardgateway.net/access_token" \
    "grant_type=authorization_code" \
    "client_id=$client_id" \
    "client_secret=$client_secret" \
    "redirect_uri=$redirect_uri" \
    "code=$authorization_code"

Example response

{
    "access_token": "access_token",
    "refresh_token": "refresh_token",
    "token_type": "Bearer",
    "expires_in": 3600
}

When you receive an authorization code, exchange it for an access token. The resulting access token is tied to both your client and an individual Reward Gateway user, and is valid for 1 hour.

Parameter Required Description
grant_type true This must be set to authorization_code
client_id true Your client ID.
client_secret true Your client secret.
redirect_uri true The URL in your app where users were sent after authorisation.
code true The authorization code you received when the user was redirected back to your app.

Authenticating requests

Example request

http "https://api.rewardgateway.net/user/me" \
    "Authorization: Bearer $access_token"

All requests must be authenticated with an access token supplied in the Authorization header using the Bearer scheme. Your client may only have one active access token at a time, per user. Acquiring a new access token will invalidate any other token you own for that user.

To get information about an access token, you can call the /user/me endpoint.

Refreshing access

Example request

http --form POST "https://identity.rewardgateway.net/access_token" \
    "grant_type=refresh_token" \
    "client_id=$client_id" \
    "client_secret=$client_secret" \
    "refresh_token=$refresh_token"

Example response

{
    "access_token": "access_token",
    "refresh_token": "refresh_token",
    "token_type": "Bearer",
    "expires_in": 3600
}

Each access token expires after 1 hour. To gain long-lived access to a user’s account, it’s necessary to “refresh” your access when it expires using a refresh token.

Refreshing an access token will invalidate the previous token, if it is still valid. Refreshing is a one-time operation.

Parameter Required Description
grant_type true This must be set to refresh_token
client_id true Your client ID.
client_secret true Your client secret.
refresh_token true The refresh token received along with the original access token.

Log Out

Example request

http --form POST "https://api.rewardgateway.net/auth/logout" \
    "Authorization: Bearer $access_token"

While access tokens do expire after one hour, you may wish to invalidate the token instantly at a specific time such as when a user chooses to log out of your application.

Once invalidated, the user must go through the authentication process again. You will not be able to refresh the access token.

REST API

The Reward Gateway REST API is designed to be a predictable and intuitive interface for interacting with all Reward Gateway products.

The base url for all REST API calls is: https://api.rewardgateway.net/

Endpoints

The REST API supports multiple versions which are listed below along side the relevant API Endpoints and documentation.

Version Support Documentation
v1 Deprecated v1 API Documentation
v2 Recommended v2 API Documentation
v3 Beta v3 API Documentation

Versioning

Example request with a specific version

http --form POST "https://api.rewardgateway.net/user/me" \
    "Authorization: Bearer $access_token" \
    "Accept: application/vnd.rewardgateway+json;version=2.0"

To access a specific version of the REST API, an Accept header MUST be passed. If no Accept header is passed Reward Gateway would automatically default to least supported version (Recommended version above).

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 by Reward Gateway?

Reward Gateway currently supports SCIM version 1.1 and SCIM version 2.0.

Authentication

Reward Gateway SCIM API uses oAuth 2.0 for authenticating requests. However, this is slightly different to authenticating requests with the REST API as explained here.

As SCIM API is used to provision users across a specific tenant, a special delegated token which is scoped to do so must be used. To obtain one of these delegated tokens, please go into the Integration Dashboard on Reward Manager and choose SCIM API.

This will generate you the following:

  1. A unique SCIM API Base URL
  2. An access token for sending authenticated requests

The base url for all SCIM Requests follows this format: https://api.rewardgateway.net/{programme_guid}/scim/{version}/

Supported Methods

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users \
  -H 'Authorization: Bearer $delegated_token' \
  -H 'Accept: application/json'

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.

You MUST provide a JSON request body for POST, PUT, and PATCH write operations.

Endpoints

Service Provider Configurations

GET /ServiceProviderConfigs

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/ServiceProviderConfigs \
  -H 'Accept: application/json'

Example response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "patch": {
        "supported": true
    },
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "filter": {
        "supported": true,
        "maxResults": 10
    },
    "changePassword": {
        "supported": true
    },
    "sort": {
        "supported": false
    },
    "etag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "name": "OAuth Bearer Token",
            "description": "Authentication scheme using the OAuth Bearer Token Standard",
            "specUri": "http://www.rfc-editor.org/info/rfc6750",
            "type": "oauthbearertoken",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "ServiceProviderConfig",
        "location": "v2/ServiceProviderConfig"
    }
}

Returns Reward Gateway’s configuration details for the client platform SCIM API. This includes which operations are supported. Learn More

Schemas

GET /Schemas/User

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Schemas/User \
  -H 'Accept: application/json' \

Example response

{
    "id": "urn:ietf:params:scim:schemas:core:2.0:User",
    "name": "User",
    "description": "Core User",
    "schema": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "schemaExtensions": {
        "schema": "urn:ietf:params:scim:schemas:rewardgateway:2.0:User",
        "required": false
    },
    "endpoint": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Schemas/User",
    "attributes": {
        "id": {
            "name": "id",
            "type": "string",
            "description": "Unique attribute defined by the Service Provider",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readOnly",
            "returned": "always",
            "uniqueness": "server",
            "subAttributes": []
        },
        "externalId": {
            "name": "externalId",
            "type": "string",
            "description": "Unique identifier defined by the Identity Provider or SCIM provider (Will take precedence over userName)",
            "multiValued": false,
            "required": false,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "server",
            "subAttributes": []
        },
        "userName": {
            "name": "userName",
            "type": "string",
            "description": "A service provider's unique identifier for the user, typically used to directly authenticate to SCIM provider.",
            "multiValued": false,
            "required": true,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "server",
            "subAttributes": []
        },
        "password": {
            "name": "password",
            "type": "string",
            "description": "Password for the user",
            "multiValued": false,
            "required": false,
            "caseExact": true,
            "mutability": "writeOnly",
            "returned": "never",
            "uniqueness": "none",
            "subAttributes": []
        },
        "name": {
            "name": "name",
            "type": "complex",
            "description": "Components of the users real name",
            "multiValued": false,
            "required": true,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": {
                "familyName": {
                    "name": "familyName",
                    "type": "string",
                    "description": "Family Name of the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "givenName": {
                    "name": "givenName",
                    "type": "string",
                    "description": "Given Name of the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                }
            }
        },
        "emails": {
            "name": "emails",
            "type": "complex",
            "description": "Components of the users email address",
            "multiValued": true,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": {
                "value": {
                    "name": "value",
                    "type": "string",
                    "description": "Email address of the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "primary": {
                    "name": "primary",
                    "type": "boolean",
                    "description": "Indicate if the email address is the primary email for the user",
                    "multiValued": false,
                    "required": true,
                    "caseExact": false,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                }
            }
        },
        "locale": {
            "name": "locale",
            "type": "string",
            "description": "A string value indicating the User's locale. e.g. en-US, en-GB",
            "multiValued": false,
            "required": false,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        },
        "active": {
            "name": "active",
            "type": "boolean",
            "description": "A Boolean value indicating the User's status.",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        },
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
            "name": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "type": "complex",
            "description": "The following SCIM extension defines attributes commonly used in representing users that belong to, or act on behalf of a business or enterprise.",
            "multiValued": false,
            "required": false,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": {
                "costCenter": {
                    "name": "costCenter",
                    "type": "string",
                    "description": "Identifies a Cost Center",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "organization": {
                    "name": "organization",
                    "type": "string",
                    "description": "Identifies an Organisation",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "division": {
                    "name": "division",
                    "type": "string",
                    "description": "Identifies a Division",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "department": {
                    "name": "department",
                    "type": "string",
                    "description": "Identifies a Department",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": []
                },
                "manager": {
                    "name": "manager",
                    "type": "complex",
                    "description": "The User's manager. A complex type that optionally allows Service Providers to represent organizational hierarchy by referencing the \\\"id\\\" attribute of another User.",
                    "multiValued": false,
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "always",
                    "uniqueness": "none",
                    "subAttributes": {
                        "managerId": {
                            "name": "managerId",
                            "type": "string",
                            "description": "The external id of the SCIM resource representing the User's manager.",
                            "multiValued": false,
                            "required": false,
                            "caseExact": true,
                            "mutability": "readWrite",
                            "returned": "always",
                            "uniqueness": "none",
                            "subAttributes": []
                        },
                        "value": {
                            "name": "value",
                            "type": "string",
                            "description": "The SCIM resource id of the SCIM resource representing the User's manager. ",
                            "multiValued": false,
                            "required": true,
                            "caseExact": false,
                            "mutability": "readWrite",
                            "returned": "always",
                            "uniqueness": "none",
                            "subAttributes": []
                        }
                    }
                }
            }
        },
        "roles": {
            "name": "roles",
            "type": "complex",
            "description": "List of user roles assigned to the member",
            "multiValued": false,
            "required": false,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        },
        "urn:ietf:params:scim:schemas:rewardgateway:2.0:User": {
            "name": "urn:ietf:params:scim:schemas:rewardgateway:2.0:User",
            "type": "complex",
            "description": "The following SCIM extension defines attributes that are custom to your organisation and are configured through Reward Manager.",
            "multiValued": false,
            "required": false,
            "caseExact": true,
            "mutability": "readWrite",
            "returned": "always",
            "uniqueness": "none",
            "subAttributes": []
        }
    },
    "meta": {
        "resourceType": "Schema",
        "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Schemas/User"
    }
}

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.

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 that Slack uses. 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

Reward Gateway 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 True 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
Licence Country locale Locale1 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.value Line Manager associated with the member Multi-Valued False False

[1] The locale is specified in the format “en_[CountryCode]”, where CountryCode follows the two letter ISO 3166-1 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

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Example response

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 2,
    "startIndex": 1,
    "itemsPerPage": 10,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "id": "8ab860d9-891f-4f8d-b454-9a012e001b92",
            "externalId": "",
            "userName": "",
            "name": {
                "familyName": "User",
                "givenName": "A"
            },
            "photos": [
                {
                    "value": "https://static.cdn.rewardgateway.net/BrandAssets/responsive/img/avatars/200x200_default-5.png",
                    "type": "photo"
                }
            ],
            "emails": [
                {
                    "value": "user.a@example.com",
                    "primary": true
                }
            ],
            "locale": "",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "costCenter": "",
                "organization": "",
                "division": "",
                "department": "",
                "manager": {
                    "managerId": "",
                    "value": ""
                }
            },
            "roles": [],
            "active": false,
            "meta": {
                "resourceType": "User",
                "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
            ],
            "id": "8ab86436-9035-4b79-99f4-061f768665c1",
            "externalId": "",
            "userName": "",
            "name": {
                "familyName": "User",
                "givenName": "B"
            },
            "photos": [
                {
                    "value": "https://static.cdn.rewardgateway.net/BrandAssets/responsive/img/avatars/200x200_default-5.png",
                    "type": "photo"
                }
            ],
            "emails": [
                {
                    "value": "user.b@example.com",
                    "primary": true
                }
            ],
            "locale": "",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "costCenter": "",
                "organization": "",
                "division": "",
                "department": "",
                "manager": {
                    "managerId": "",
                    "value": ""
                }
            },
            "roles": [],
            "active": false,
            "meta": {
                "resourceType": "User",
                "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Users/8ab86436-9035-4b79-99f4-061f768665c1"
            }
        }
    ]
}

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 equal
lt Less than
le Less than or equal
and Logical And
or Logical Or

Other examples of filtering

Paginating (Finding the first 50 users)

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?startIndex=1&count=50 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Paginating (Finding the second set of 50 users)

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?startIndex=50&count=50 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Searching users with userName

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=userName eq "jane.doe@example.com" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Searching users with either userName or familyName

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=userName eq "jane.doe@example.com" OR familyName eq "Doe" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Searching users with names like

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users?filter=givenName co "ja" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

GET /Users/{id}

Example request

curl -X GET https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Example response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "8ab860d9-891f-4f8d-b454-9a012e001b92",
    "externalId": "",
    "userName": "",
    "name": {
        "familyName": "User",
        "givenName": "A"
    },
    "photos": [
        {
            "value": "https://static.cdn.rewardgateway.net/BrandAssets/responsive/img/avatars/200x200_default-5.png",
            "type": "photo"
        }
    ],
    "emails": [
        {
            "value": "user.a@example.com",
            "primary": true
        }
    ],
    "locale": "",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "costCenter": "",
        "organization": "",
        "division": "",
        "department": "",
        "manager": {
            "managerId": "",
            "value": ""
        }
    },
    "roles": [],
    "active": false,
    "meta": {
        "resourceType": "User",
        "location": "/8bc011dd-cc27-4232-a93d-18c98637f734/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92"
    }
}

Returns a single user resource. The value of the {id} must be the user's corresponding Member ID (UUID) in Reward Gateway.

POST /Users

Example request

curl -X POST https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Example request body

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "name": {
        "givenName": "User",
        "familyName": "C"
    },
    "emails": [{
        "primary": true,
        "value": "user.c@example.com",
        "type": "work"
    }],
    "externalId": "ABCDE",
    "password": "password"
    "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"
        }
    }
}

Creates a new user on the client programme. Must include all required fields mentioned in the SCIM API Attributes Mapping section.

PATCH /USERS/{id}

Example request

curl -X PATCH https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Example request body

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "name": {
        "givenName": "User",
        "familyName": "ABC"
    },
    "active": true
}

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

PUT /USERS/{id}

Example request

curl -X PUT https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Example request body

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User","urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "name": {
        "givenName": "User",
        "familyName": "A"
    },
    "emails": [{
        "primary": true,
        "value": "user.a.changed@example.com",
        "type": "work"
    }],
    "externalId": "user.a.changed@example.com",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "costCenter": "Cost Center A",
        "organization": "Organization A",
        "manager": {
            "managerId": "K18762212"
        }
    }
}

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

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}

Example request

curl -X DELETE https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Users/8ab860d9-891f-4f8d-b454-9a012e001b92 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

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.

POST /BULK

Example request

curl -X POST https://api.rewardgateway.net/8a98e6b3-d06d-4c18-85d7-fc239c87a2c7/scim/v2/Bulk \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $delegated_token' \

Example request body

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "Operations": [
        {
            "method": "POST",
            "path": "/User",
            "data": {
                "userName": "test7@test.com",
                "name": {
                    "givenName": "test",
                    "familyName": "test"
                },
                "emails": [
                    {
                        "value": "test7@test.com",
                        "primary": true
                    }
                ],
                "active": true
            }
        },
        {
            "method": "POST",
            "path": "/User",
            "data": {
                "userName": "test8@test.com",
                "name": {
                    "givenName": "test",
                    "familyName": "test"
                },
                "emails": [
                    {
                        "value": "test8@test.com",
                        "primary": true
                    }
                ],
                "active": true
            }
        }
    ]
}

Creates new users on the client programme. Must include all required fields mentioned in the SCIM API Attributes Mapping section.

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

Rate Limiting

Reward Gateway APIs rely on rate limits to help provide a predictably pleasant experience for users. Rate limits are applied to all API endpoints regardless of which api you use.

Our current rate limits are set to: 180 requests for a 15 minute window. These limits are per endpoint, per unique ip address. These are also represented through headers in each response returned from the APIs.

Header Description
X-Rate-Limit-Limit Max allowed requests
X-Rate-Limit-Remaining Remaining requests in the current window
X-Rate-Limit-Reset Time until current window expires

Acceptable Use Policy

This Acceptable Use Policy (“Policy”) applies to the use of the Reward Gateway API.

As used in this Policy, “API” means programmatic web APIs and associated tools and documentation that Reward Gateway makes available to Reward Gateway customers and partners under this Policy.

This Policy was last updated on February 7, 2021.

Reward Gateway may change this Policy by posting an updated version on the Reward Gateway API Documentation Portal and such updates will be effective immediately.

Responsibility of the User

Users agree to use Reward Gateway’ services in a manner that is legal, appropriate and in conformity with industry standards.

Users will not use the Reward Gateway API to distribute any virus, spyware, adware, malware, or other harmful or malicious component.

Users will not use the Reward Gateway API in any way which or might overburden, impair or disrupt the Reward Gateway API or related servers or networks.

Users will not perform significant load or security testing of the Reward Gateway API without first obtaining Reward Gateway’s written consent.

Violation

If a customer’s breaches any of the terms within this Policy, Reward Gateway may immediately remove access to the Reward Gateway API.

Reward Gateway may also consider such a violation a material breach of the Client Agreement and/or other agreement governing the customer’s use of the services.

Jurisdiction

This Policy shall be governed by the laws under which the Customer ordered a Reward Gateway service and/or other agreement governing the customer’s use of the services.