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:
- Acquire an access token, and a refresh token
- Use the access token to make authenticated requests
- 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):
- Redirect the user to Reward Gateway Identity to authorise your app
- Reward Gateway Identity redirects the user back to your app with an authorization code
- 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:
- 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 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:
- A unique SCIM API Base URL
- 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.
- GET – Retrieve Information about a User or Users.
- POST – Create a new user.
- PUT / PATCH – Modify a user.
- DELETE – Remove a user.
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.