Skip to content
CrowdStrike Developer Center

Identity Protection

The Identity Protection service collection provides operations for managing identity-based security across your environment. Retrieve sensor aggregates, get device details, search sensors by filter, execute GraphQL queries for entities and incidents, and manage identity protection policy rules.

LanguageLast Update
Pythonv1.5.3
PowerShellv2.2.9
Gov0.20.0
TypeScriptv0.6.0
Rustv0.7.0
Rubyv1.2.0

Table of Contents

Section titled “Table of Contents”
OperationDescription
GetSensorAggregates
get_sensor_aggregates		Get sensor aggregates as specified via json in request body.
GetSensorDetails
get_sensor_details		Get details on one or more sensors by providing device IDs in a POST body. Supports up to a maximum of 5000 IDs.
QuerySensorsByFilter
query_sensors		Search for sensors in your environment by hostname, IP, and other criteria.
api_preempt_proxy_post_graphql
graphql		Identity Protection GraphQL API. Allows to retrieve entities, timeline activities, identity-based incidents and security assessment. Allows to perform actions on entities and identity-based incidents.
get_policy_rules
get_policy_rules		Get policy rules.
post_policy_rules
create_policy_rule		Create policy rules.
delete_policy_rules
delete_policy_rules		Delete policy rules.
get_policy_rules_query
query_policy_rules		Query policy rule IDs.

GetSensorAggregates

Section titled “GetSensorAggregates”

Get sensor aggregates as specified via json in request body.

POST /identity-protection/aggregates/devices/GET/v1
Scope Identity Protection Entities: READ Consumes · Produces application/json
PEP 8 get_sensor_aggregates

Parameters

Section titled “Parameters”
NameTypeData typeDescription
bodybodylist of dictionariesFull body payload in JSON format.
date_rangesbodylist of dictionariesApplies to date_range aggregations. Example: [{“from”: “2016-05-28T09:00:31Z”, “to”: “2016-05-30T09:00:31Z”}, {“from”: “2016-06-01T09:00:31Z”, “to”: “2016-06-10T09:00:31Z”}]
excludebodystringElements to exclude.
fieldbodystringThe field on which to compute the aggregation.
filterbodystringFQL syntax formatted string to use to filter the results.
frombodyintegerStarting position.
includebodystringElements to include.
intervalbodystringTime interval for date histogram aggregations. Valid values include: year, month, week, day, hour, minute.
max_doc_countbodyintegerOnly return buckets if values are less than or equal to the value here.
min_doc_countbodyintegerOnly return buckets if values are greater than or equal to the value here.
missingbodystringMissing is the value to be used when the aggregation field is missing from the object. In other words, the missing parameter defines how documents that are missing a value should be treated. By default they will be ignored, but it is also possible to treat them as if they had a value.
namebodystringName of the aggregate query, as chosen by the user. Used to identify the results returned to you.
qbodystringFull text search across all metadata fields.
rangesbodylist of dictionariesApplies to range aggregations. Ranges values will depend on field. For example, if max_severity is used, ranges might look like: [{“From”: 0, “To”: 70}, {“From”: 70, “To”: 100}]
sizebodyintegerThe max number of term buckets to be returned.
sub_aggregatesbodylist of dictionariesA nested aggregation, such as: [{“name”: “max_first_behavior”, “type”: “max”, “field”: “first_behavior”}]. There is a maximum of 3 nested aggregations per request.
sortbodystringFQL syntax string to sort bucket results. _count - sort by document count. _term - sort by the string value alphabetically. Supports asc and desc using \| format. Example: _count\|desc
time_zonebodystringTime zone for bucket results.
typebodystringType of aggregation. Valid values include: date_histogram - Aggregates counts on a specified time interval. Requires use of “interval” field. date_range - Aggregates counts on custom defined date range buckets. terms - Buckets alerts by the value of a specified field. range - Buckets alerts by specified (numeric) ranges of a specified field. cardinality - Returns the count of distinct values in a specified field. max - Returns the maximum value of a specified field. min - Returns the minimum value of a specified field. avg - Returns the average value of the specified field. sum - Returns the total sum of all values for the specified field. percentiles - Returns the following percentiles for the specified field: 1, 5, 25, 50, 75, 95, 99.

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


ranges = [
    {
        "From": 0,
        "To": 0
    }
]


response = falcon.get_sensor_aggregates(date_ranges="string",
                                        exclude="string",
                                        field="string",
                                        filter="string",
                                        from=integer,
                                        include="string",
                                        interval="string",
                                        max_doc_count=integer,
                                        min_doc_count=integer,
                                        missing="string",
                                        name="string",
                                        q="string",
                                        ranges=ranges,
                                        size=integer,
                                        sort="string",
                                        sub_aggregates=["string"],
                                        time_zone="string",
                                        type="string")
print(response)

GetSensorDetails

Section titled “GetSensorDetails”

Get details on one or more sensors by providing device IDs in a POST body. Supports up to a maximum of 5000 IDs.

POST ​/identity-protection​/entities​/devices​/GET​/v1
Scope Identity Protection Entities: READ Consumes · Produces application/json
PEP 8 get_sensor_details

Parameters

Section titled “Parameters”
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
idsbodystring or list of stringsThe host agent IDs used to get details on. Maximum: 5000

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']


response = falcon.get_sensor_details(ids=id_list)
print(response)

QuerySensorsByFilter

Section titled “QuerySensorsByFilter”

Search for sensors in your environment by hostname, IP, and other criteria.

GET /identity-protection/queries/devices/v1
Scope Identity Protection Entities: READ Consumes · Produces application/json
PEP 8 query_sensors

Parameters

Section titled “Parameters”
NameTypeData typeDescription
offsetqueryintegerThe offset to start retrieving records from
parametersquerydictionaryFull query string parameters payload in JSON format.
limitqueryintegerThe maximum records to return. [1-200]
sortquerystringThe property to sort by (e.g. status.desc or hostname.asc)
filterquerystringThe filter expression that should be used to limit the results.

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


response = falcon.query_sensors(filter="string",
                                limit=integer,
                                offset=integer,
                                sort="string")
print(response)

api_preempt_proxy_post_graphql

Section titled “api_preempt_proxy_post_graphql”

Identity Protection GraphQL API. Allows to retrieve entities, timeline activities, identity-based incidents and security assessment. Allows to perform actions on entities and identity-based incidents.

POST /identity-protection/combined/graphql/v1
Scope Identity Protection GraphQL: WRITE Consumes · Produces application/json
PEP 8 graphql

Parameters

Section titled “Parameters”
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
querybodystringJSON-similar formatted query to perform.
variablesbodydictionaryDictionary of variables to provide to the query.

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


response = falcon.graphql(query="string", variables={})
print(response)

get_policy_rules

Section titled “get_policy_rules”

Get policy rules.

GET /identity-protection/entities/policy-rules/v1
Scope Identity Protection Policy Rules: READ Consumes · Produces application/json
PEP 8 get_policy_rules

Parameters

Section titled “Parameters”
NameTypeData typeDescription
parametersquerydictionaryFull query string payload in JSON format.
idsquerystring or list of stringsThe policy rule IDs used to get details on.

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']


response = falcon.get_policy_rules(ids=id_list)
print(response)

post_policy_rules

Section titled “post_policy_rules”

Create policy rules.

POST /identity-protection/entities/policy-rules/v1
Scope Identity Protection Policy Rules: WRITE Consumes · Produces application/json
PEP 8 create_policy_rule

Parameters

Section titled “Parameters”
NameTypeData typeDescription
bodybodydictionaryFull body payload in JSON format.
destinationquerydictionaryActivity destination.
enabledquerybooleanFlag indicating if the policy rule is enabled.
namequerystringName of the policy rule.
simulation_modequerybooleanSimulate the policy action instead of actually taking action.
source_endpointquerydictionarySource endpoint details.
source_userquerydictionarySource user details.
triggerquerystringPolicy rule trigger.

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


response = falcon.create_policy_rule(action="string",
                                     activity={},
                                     destination={},
                                     enabled=boolean,
                                     name="string",
                                     simulation_mode=boolean,
                                     source_endpoint={},
                                     source_user={},
                                     trigger="string")
print(response)

delete_policy_rules

Section titled “delete_policy_rules”

Delete policy rules.

DELETE /identity-protection/entities/policy-rules/v1
Scope Identity Protection Policy Rules: WRITE Consumes · Produces application/json
PEP 8 delete_policy_rules

Parameters

Section titled “Parameters”
NameTypeData typeDescription
parametersquerydictionaryFull query string payload in JSON format.
idsquerystring or list of stringsThe policy rule IDs to delete.

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']


response = falcon.delete_policy_rules(ids=id_list)
print(response)

get_policy_rules_query

Section titled “get_policy_rules_query”

Query policy rule IDs.

GET /identity-protection/entities/policy-rules/v1
Scope Identity Protection Policy Rules: READ Consumes · Produces application/json
PEP 8 query_policy_rules

Parameters

Section titled “Parameters”
NameTypeData typeDescription
enabledquerybooleanFlag indicating if the rule is enabled.
parametersquerydictionaryFull query string parameters payload in JSON format.
simulation_modequerybooleanFlag indicating if the rule is in simulation mode.
namequerystringRule name

Code Examples

Section titled “Code Examples”
from falconpy import IdentityProtection


falcon = IdentityProtection(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )


response = falcon.query_policy_rules(enabled=boolean,
                                     simulation_mode=boolean,
                                     name="string")
print(response)
© 2026 CrowdStrike, Inc. All rights reserved. Privacy Notice Cookie Notice Terms of Use