Skip to navigation
BotBye APIProtectionCompromised Users

list

View as Markdown

Retrieves a paginated list of project users whose credentials were entered on a phishing site, deduplicated to one row per user.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/compromised-users

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

ParameterTypeRequiredDescription
account_idstringYesYour unique BotBye account identifier
project_idstringYesThe project to retrieve compromised users for

Query Parameters

  • Pagination: cursor-based (cursor, limit). By default limit is 20, max 100.
  • Filtering: where supports filtering on the available fields (e.g. phishing_origin).
  • Ordering: order_by — results are keyed by account_id.

Response Structure

Cursor-based pagination. Each node is one compromised user:

FieldTypeDescription
idstringStable node id, "{accountId}:{projectId}" (unique within the project)
accountIdstringThe end-user account id as reported by the integration
phishingOriginstringOrigin of the most recent compromised login (latest wins)
lastLoginAtstringTimestamp (epoch millis) of the most recent compromised login

pageInfo carries hasPreviousPage, hasNextPage, startCursor, endCursor and total (the distinct number of compromised users).

Use Cases

  • Incident response: identify which users to force-reset after a phishing campaign.
  • Customer notification: surface affected accounts to warn end users.
  • Campaign analysis: group compromised users by the phishing origin that captured them.

Accepted permissions Project → ATO info → ATO info

Token scope ATO Info View

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Path parameters

account_idstringRequired
project_idstringRequired

Query parameters

cursorstringOptional

(Optional): a cursor for pagination.

  • after (string): Pointer to the item after which the items are to be retrieved.
  • before (string): Pointer to the item before which the items are to be retrieved.
wherestringOptional

(Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes).

  • predicate (string): The filtering condition (e.g., gte, lte, eq for a leaf or and, or for a branch). Possible values [[#Predicate]]
  • opearands (string): A list of nested conditions (used only for branches, such as and, or).
  • fieldPath (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list).
  • value (string): The value to compare against the field (used only for a leaf).
order_bystringOptional

(Optional): property by which to order by.

  • fieldPath (string): name of order field.
  • direction (string): ASC or DESC
limitstringOptional

(Optional): specifies the maximum number of results to return in a single response. By default - 20, max - 100.

Response headers

Content-Lengthinteger
ConnectionstringOptional

Response

success
edgeslist of objects
pageInfoobject
attributesobject

Errors

400
Bad Request Error