Set up an operation

If you use Bot Manager Premier or Account Protector, you come to the API Definitions app to register the transactional endpoint, like the login or checkout page, you want to protect. To do so—even if that page isn't technically an API—you define an API (to share the page's path and other details) and create an operation (formerly called resource purpose).

  1. On the API Definitions page, in the Registered APIs section, find the API definition in which you want to create an operation and click its ... Action menu.

  2. From the menu, select Manage versions.

  3. In the Version history panel, select the version you want to edit.

  4. From the list of delivery options on the left, select API Operations.

  5. On the API Operations page, click + to add a new operation.

  6. Enter the Name of the operation.
    If you only specify one operation for a resource, it’s best to use the same name for the operation as you did for the resource. This helps you easily identify it in your security configuration. If you specify multiple operations of a resource (for example, two different operations for GET and POST), use the name of the resource in combination with the method. For example: post-book.

  7. Select the associated API resource.
    You can create up to 200 operations per resource.

  8. From the Method menu, select the HTTP method used in combination with the resource.

  9. Click Operation Purpose and select the task your transactional page serves.

📘

If you can’t find the exact task on the list, select the most similar option.

  • Login: This operation allows the user to log on to their account – either a bank account, an eCommerce one, etc.

    If you selected Login, go to the Username parameter menu, select the login parameter you defined in the API resource panel.
    If the value you want to capture, like username, is in a JSON array, and you turned on the array checkbox when you set up this resource, enter the array index numbers to share where username data lives. This is a number that specifies a value’s position in the array and starts at zero. For example, in this JSON object:

    {  
     "gateway_customer": {  
         "identities": {  
             "identity": [  
                 {  
                     "data": "test@example.com",  
                     "type": "USERNAME"  
                 },  
                 {  
                     "data": "qwerty123",  
                     "type": "PASSWORD"  
                 }  
             ]  
         }  
     }  
    }
    

    the username parameter is: /gateway_customer/identities/identity and the username index is at the first level, so you’d enter an index value of: 0

    If the path has multiple array elements, you must specify an index for each one.

    Note: Your code must enforce the defined array order, so values are always found in the same index.

  • Account Creation: This operation allows the user to open a new account.

    If you selected Account Creation and are part of our Account Opening Abuse beta program, you must make a selection in the User Data Parameters section which appears. Select at least one value you use to identify users and specify the parameter where that user identification value lives. For example, if your visitors log in with their email address, then beside Email, enter the parameter where email addresses live and turn on its Used for login checkbox. You can select and specify several ID parameters here. Note that the first value in the list that you specify as login, appears in reports as username, even if it is an email value or other identifier.

  • Account Verification: This operation verifies if an account exists. For example, you can use it on a page meant for logging in to or creating an account. When the user enters their email address in a form, if there is an account tied to that address, they are asked for their password and then logged in. If there is no account tied to their address, they are redirected to the account creation process.

  • Add to Cart: This operation allows the user to add an item to their cart.

  • Giftcard Balance Check: This operation allows the user to enter identifying information, such as a card number and PIN, to view their gift card balance.

  • Loyalty Points: This operation allows the user to enter identifying information and view the amount of loyalty points they have for the retailer.

  • Password Reset: This operation allows the user to get a new password when they don’t know the previous one. For example, the user enters their email address in a form, then proves their identity by clicking a link they got in an email, and chooses a new password. Note that you can define the username and Origin Response Success/Origin Response Failure parameters for this operation.

  • Search: This operation allows the user to enter a word into the search bar to look for a specific product or service on a company website.

    If you are a part of the Account Lifecycle Protection beta program, you can choose from the additional operation purposes:

    Note that the user has to be logged in to perform these operations.

  • Account Update: This operation allows updating details on the user’s account, such as email address, phone number, credit card number, etc.

  • Password Change: This operation allows changing the password, for example, if the user’s previous password was compromised or if they want to change it regularly for safety reasons.

  • Payment: This operation allows conducting checkout transactions or money transfers.

📘

The Account Lifecycle Protection beta program allows you to optionally provide a username for the following operations:

  • Account Update
  • Password Change
  • Payment

If you don’t do that, Account Protector generates a risk score based on the most recently seen username that logged in successfully from a client with the same long-term Bot Manager cookie.
Usernames should only be configured if they are validated by the origin against the active session. Consuming a username that can be injected by an attacker and that is different from the authenticated session will cause incorrect risk scores for such a request.

  1. If you use Account Protector, you can tell it where to find the unique ID you use to track your end-users. This is called Origin User ID BETA In the Origin User ID section, select the location of your unique ID:
  • Response Header then enter the name of the header.
  • Set-cookie Currently under development. To use Set-cookie, contact your account team.

🚧

If you want to share origin user ID from your mobile app token, it must be a long-lived token that remains constant through multiple logins and is valid for a month or longer. When you set up your origin user id, specify only the field containing the token. Also, have your origin send the origin user ID in the response to the login request.

  1. To capture data on successful and unsuccessful attempts to use the resource, in the Origin Response section, define their traits.
    You need to configure origin response for transactional endpoints if you use Account Protector. For Bot Manager Premier this step is optional.
    You can set up success and failure reporting for every operation type except Search and Add to cart.
    click Add to create your conditions in the Success conditions and/or Failure conditions sections.

    a. In Response Code, select matches or does not match, and enter the code you want to track, like 401.
    You can enter multiple codes.

    b. In Response Header, enter the header name, select matches or does not match, and enter the value you want to track.
    To add another response header, click Add.

    c. In Set-cookie, enter the cookie name and select matches or does not match.
    You can use * and ? wildcards and you can turn the Case-sensitive switch on.

    If you define:
    – only failure conditions, then any other activity on the endpoints is treated as success.
    – only success, then any other activity is a failure.
    – both failure and success, then any other activity is labeled as unknown.
    – no conditions, then all activity on the endpoints is labeled as unknown.
    – multiple values of the same condition (for example, response code = 200, 201), then the success or failure condition is met if any of these values apply.
    – multiple conditions (response code = 200, response header = X-LoginSuccess:true), then the success or failure condition is met only if all of these conditions apply.

📘

Unknown is also a label applied in a scenario where bot management detections are bypassed, like when you set an exception, or when the request is denied, allowed, or ignored by an earlier protection and account protection doesn't run.

After you set the conditions, the successes, failures and unknown activity appear in the Bot Endpoint Protection report.

  1. Optional: If requests to protect using Bot Manager Premier or Account Protector always include parameters, then in the Additional required parameters section, do the following for every parameter that you want to set up:

Note: Usually, you won't add parameter criteria here. Do so if you want to protect ONLY specific requests that include or exclude the parameter. Requests that don't meet the conditions you set won't undergo Bot Manager Premier detection nor Account Protector evaluation.

a. Click Add parameter

b. From the leftmost drop-down menu, select the parameter that you want to configure. If it contains array indexes, you must specify their location. Enter the index in the box provided. To see an example, refer back to Step 9.

c. From the rightmost drop-down menu, select the condition that the parameter should meet.

d. If you selected the matches or does not matchcondition, enter the text for parameter.

🚧

Again, don't enter parameter criteria here unless you want to protect ONLY those specific requests. If your app accepts requests that don't meet the parameter conditions you define, those requests would likely bypass bot protections. Proceed carefully. The need to set parameters here is rare (for example, in the case of GraphQL applications).

  1. Click Save.