Identifying accounts that show related behaviors

This document describes how to identify accounts that show related behaviors. For example, you might want to identify all user accounts that are created by a malicious user. You can find accounts, account groups, and account group memberships that show related behaviors.

Identifying accounts that show related behaviors helps you find groups of fake accounts and account takeovers when a previously legitimate account is related to accounts with abusive behavior.

This feature is only available using the reCAPTCHA Enterprise REST API and Client libraries.

To retrieve a list of accounts related to a specified account, use the relatedaccountgroupmemberships.search method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID.
  • HASHED_ACCOUNT_ID: a stable hashed user identifier generated using the SHA256-HMAC method for a user account on your website.
  • PAGE_SIZE: Optional. The number of account memberships to include in the response. The default value is 50, and the maximum value is 1,000. If the number of account memberships is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • NEXT_PAGE_TOKEN: Optional. The value of nextPageToken returned in the earlier response of this method. Specify this parameter to query more account memberships.

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroupmemberships:search?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN

Request JSON body:

{
  "hashedAccountId": "HASHED_ACCOUNT_ID"
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroupmemberships:search?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN"

PowerShell

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroupmemberships:search?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "relatedAccountGroupMemberships": [
    {
      "name": "projects/projectId/relatedaccountgroups/groupId187/memberships/membershipId95",
      "hashedAccountId": "4RopXS59"
    },
    {
      "name": "projects/projectId/relatedaccountgroups/groupId91/memberships/membershipId23",
      "hashedAccountId": "HVMv1DTb"
    }
  ],

  "nextPageToken": "Q2N_rZgxUXOjNZtK1T1i0Q"
}

Code sample

Retrieve related account groups

To retrieve a list of account groups with similar behaviors, use the relatedaccountgroups.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID.
  • PAGE_SIZE: Optional. The number of account groups to include in the response. The default value is 50, and the maximum value is 1,000. If the number of account groups is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • NEXT_PAGE_TOKEN: Optional. The value of nextPageToken returned in an earlier response of this method. Specify this parameter to query more account groups.

HTTP method and URL:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroups?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroups?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN"

PowerShell

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroups?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "relatedAccountGroups": [
    {
      "name": "projects/projectId/relatedaccountgroups/groupId1"
    },
    {
      "name": "projects/projectId/relatedaccountgroups/groupId2"
    }
  ],
  "nextPageToken": "BenimQwKzIOibbOO2Lhisw"
}

Code sample

Retrieve related account group memberships

To retrieve a list of account group memberships with similar behaviors, use the relatedaccountgroupmemberships.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID.
  • GROUP_ID: Name of the account group for which you want to find related memberships.
  • PAGE_SIZE: Optional. The number of account group memberships to include in the response. The default value is 50, and the maximum value is 1,000. If the number of account group memberships is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
  • NEXT_PAGE_TOKEN: Optional. The value of nextPageToken returned in the earlier response of this method. Specify this parameter to query more account group memberships.

HTTP method and URL:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroups/GROUP_ID/memberships?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroups/GROUP_ID/memberships?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN"

PowerShell

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/relatedaccountgroups/GROUP_ID/memberships?page_size=PAGE_SIZE&page_token=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "relatedAccountGroupMemberships": [
    {
      "name": "projects/projectId/relatedaccountgroups/groupId/memberships/membershipId1",
      "hashedAccountId": "4RopXS59"
    },
    {
      "name": "projects/projectId/relatedaccountgroups/groupId/memberships/membershipId2",
      "hashedAccountId": "HVMv1DTb"
    }
  ],
  "nextPageToken": "WPuIn8GHU3JvcJqgvmE7Aw"
}

Code sample

What's next