For all endpoints, you will need to authenticate requests using the OAuth2.0 Client Credentials Grant flow.

First, you need to obtain an access token by authenticating with the OAuth2.0 authorization server using your client credentials (client ID and client secret). This token is short-lived and must be used to sign your requests. The process involves the following steps:

1. Obtain Access Token

• Send a POST request to the token endpoint of the authorization server (https://apps.auth.rewards.gov.sg/oauth2/token) with your client credentials.
• Refer to the AWS Cognito OAuth2.0 Client Credentials Grant flow documentation for detailed instructions on obtaining an access token using the Token Endpoint.

2. Use Access Token

• Once you have the access token, include it in the Authorization header of your HTTP requests to the API endpoints.
• The token should be prefixed with the type Bearer.

Example Request to Obtain Access Token

POST /oauth2/token HTTP/2
Host: apps.auth.rewards.gov.sg
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Example Response

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

Idempotency ensures repeated identical requests produce the same result without causing unintended side effects. This is particularly vital for operations where network issues or client retries might lead to multiple identical requests being sent. By adhering to idempotency, our API guarantees that actions such as creating or updating resources can be performed safely multiple times without altering the final outcome beyond the first successful request. Implementing idempotency enhances the reliability, predictability, and robustness of our API, providing a consistent and dependable user experience.

Only POST endpoints which accept the header x-idempotency-key can have idempotent requests. DELETE and GET are idempotent by design so they do not require the header.

Including an x-idempotency-key header makes request idempotent. It has several properties:

• The x-idempotency-key is required for endpoints that accepts this header.

• Each idempotency key is valid for 24 hours.

• The idempotency key has to be a valid UUID.

• Calling subsequent requests with the same x-idempotency-key within the 24-hour window will return an idempotent-replayed header. These subsequent requests will not cause duplicate transactions.

• When the idempotent-replayed header is returned, the HTTP status code of the response will match the first request's response HTTP status code.

To ensure fair use and maintain system stability, the GovRewards API implements rate limiting at the tenant level.

Rate Limit Configuration

Note: Additional throttlers and adjustments to the rate limits may be introduced as the platform evolves.

Response Headers for Rate Limiting

Every API response will include the following headers:

Rate Limit Exceeded Response

If the rate limit is exceeded, the API will respond with:

HTTP Status: 429 Too Many Requests
Example Response:

{
  "error": {
    "reasonCode": "too_many_requests",
    "description": "The request failed because the rate limit for this endpoint has been exceeded.",
    "details": []
  },
  "requestId": "88fcd476-e3a2-43c1-b290-31fbdb91aebe"
}

Client-toggled feature flags are feature flags that can be enabled by the API client per request. This allows tenants to test and enable a new feature at their own timing. These feature flags will only be available for a period of time, after which, the feature will be enabled by default.

Usage

To enable a client-toggled feature flag, add the header x-feature-flags: feature_flag_1,feature_flag_2 to the request. If the feature flag is supported for the API endpoint, it will be added to the response header. Otherwise, it will be ignored.

For example, if feature_flag_1 and feature_flag_2 are passed in, but only feature_flag_1 is supported by the API endpoint, the response header will be x-feature-flags-enabled: feature_flag_1.

Example Request

curl --header "x-feature-flags: feature_flag_1,feature_flag_2" https://api.rewards.gov.sg/api/v1/campaigns

Example Response Header (Only feature_flag_1 is supported)

x-feature-flags-enabled: feature_flag_1

Supported Feature Flags

There are no supported client-toggled feature flags at the moment.

Conditions define the criteria that must be met for an action to be valid, such as redeeming a reward. Each condition consists of a name, an operator, and a value, which are evaluated to determine eligibility.

_build.1.9.21