Lockout API
Retrieve lockout policies and lockout data for a customer, and reset a customer's lockout counter.
Lockouts are used to keep running tallies of invalid attempts and lock customers out of various event types. Currently, the SessionM Platform supports lockouts for promotion code entry. Organizations can configure a lockout policy that dictates how many invalid promotion codes a customer can enter before they are locked out from entering any more codes. Lockout policies are configured in the platform using the SessionM Administration Portal. For more information, talk to your SessionM integration engineer.
The characteristics and constraints that constitute a lockout are configured in lockout policies. In addition to type and the datetimes that establish when it is in effect, policies contain a few other kinds of metadata about a customer's lockouts, including:
- Consecutive count -- Number of lockout-eligible events that have happened in a row since the last lockout period.
- Cumulative count -- Number of cumulative lockout-eligible events that have happened all time for the customer.
- Lockout expiration -- Time at which lockout expires.
- Lockout count resets -- Number of times lockout counts have been reset.
- Lockout duration -- Duration of lockout in seconds.
Lockout policies are one implementation of the policy object. For example, for promo code lockout policies, the type is promo_code_lockout.
API Contingencies and Combinations:
- Lockout policies return the lockout count for a customer/type pair. Therefore, you must create the customers prior to fetching the lockout counts for them. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
- Lockout policies also work with objects from the Promo Codes APIs, limiting the number of invalid promo code entries a customer can make before getting locked out of the system.
This API supports the following methods:
Retrieve a Lockout Policy and Lockout Data for a Customer
This method retrieves an existing lockout record for a customer; if none exists then the customer has no lockout record. A value for the lockout type enumeration is required.
Endpoints for Retrieve a Lockout Policy and Lockout Data for a Customer
This method offers the following endpoints:
REST Endpoints
GET /priv/v1/apps/:api_key/users/:user_id/lockout?event_type=<type>
GET /priv/v1/apps/:api_key/external/users/:external_id/lockout?event_type=<type>
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters for Retrieve a Lockout Policy and Lockout Data for a Customer
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
| event_type | If the event_type is "promo_code", retrieve a lockout policy in support of promo codes. If there is no active policy, then the policy node's value will be null; if the customer does not have a currently active lockout of type <event_type>, then the returned structure's customer node's value will be null. |
Request Object for Retrieve a Lockout Policy and Lockout Data for a Customer
Not applicable.
Response Object for Retrieve a Lockout Policy and Lockout Data for a Customer
In addition to a status key-value pair, the response object returned by the method contains two objects. They include:
- policy
- player
These objects are shown below:
JSON Response
{
"policy":
{
"id": 8,
"starts_at": "2016-08-27T22:37:29Z",
"ends_at": "2016-09-27T22:37:29Z",
"organization_id": 3627,
"type": "promo_code_lockout",
"consecutive_count" : 1000,
"cumulative_count" : 30000,
"lockout_duration" : 86400
},
"player":
{
"id" : 8776,
"event_type": "promo code",
"user_id" : "83003",
"consecutive_count" : 1000,
"cumulative_count" : 25000,
"lockout_expires" : "2016-09-27T22:37:29Z",
"reset_counter" : 1
}
}
Policy Object
The table below provides details on the policy object. Some of the attributes in the table apply only to lockout policies, while others apply only to limiter policies.
Response Attributes for Policy
| Attribute | Type | Description |
|---|---|---|
| id | integer | Lockout or limiter policy ID. |
| starts_at | datetime | ISO8601 formatted datetime at which the policy becomes effective. |
| ends_at | datetime | ISO8601 formatted datetime at which the policy stops being in effect. |
| created_at | datetime | ISO8601 formatted datetime at which the policy was created. |
| updated_at | datetime | ISO8601 formatted datetime at which the policy was updated. |
| organization_id | integer | Foreign key for organization.id. |
| type | string | Enumeration that describes policy types, such as promo_code_lockout. |
| consecutive_count | integer | Number of invalid codes that have been entered consecutively since the last lockout period expired. |
| cumulative_count | integer | The number of cumulative event types done by the customer. |
| lockout_duration | integer | Duration of lockout period. |
| data | object | Object containing specific policy configuration. See next row for more information. |
| data["quantums"] | enumeration | Enumeration that provides values that correspond to periods of time, including: weekly, monthly and yearly. |
Player Object
The following table provides details on the player object:
Response Attributes for Player
| Attribute | Type | Description |
|---|---|---|
| id | integer | Lockout ID. |
| event_type | string | Enumeration that defines the type of lockout being tracked, such as promo code. |
| user_id | string | ID of the customer being locked out. |
| consecutive_count | integer | Number of invalid codes that have been entered consecutively since the last lockout period expired. |
| cumulative_count | integer | The number of cumulative event types done by the customer. |
| lockout_expires | datetime | ISO8601 formatted datetime at which the lockout expires. |
| reset_counter | integer | Number of times lockout has been reset. |
Statuses and Errors for Retrieve a Lockout Policy and Lockout Data for a Customer
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
| Code | Reason |
|---|---|
| bad_data | Error for an invalid customer if the customer is invalid. |
| bad_data | Error for an invalid event type if event type is invalid. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.
Reset a Lockout Counter for a Customer
This method resets a lockout counter for a customer.
Endpoints for Reset a Lockout Counter for a Customer
This method offers the following endpoints:
REST Endpoints
POST /priv/v1/apps/:api_key/users/:user_id/lockout/reset
POST /priv/v1/apps/:api_key/external/users/:external_id/lockout/reset
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters for Reset a Lockout Counter for a Customer
The following parameters are available when specifying the endpoint for this method:
| Endpoint Parameter | Description |
|---|---|
| api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
| user_id | Internal identifier for the customer within the SessionM Platform. |
| external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object for Reset a Lockout Counter for a Customer
When this method runs, it passes in a request object that contains a lockout object, which is shown below:
JSON Request
{
"lockout":
{
"event_type": "promo_code"
}
}
This object is detailed in the following table:
Request Attributes for Lockout Reset
| Attribute | Type Required/Optional | Description |
|---|---|---|
| event_type | string required | Enumeration for lockout types. Possible values include the string, promo code. |
Response Object for Reset a Lockout Counter for a Customer
This method returns a status key-value pair, as shown below:
JSON Response
{
"status": "ok"
}
Statuses and Errors for Reset a Lockout Counter for a Customer
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
| Code | Reason |
|---|---|
| bad_data | Error for an invalid customer if the customer is invalid. |
| bad_data | Error for an invalid event type if event type is invalid. |
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.