Recommendations

Download OpenAPI specification:Download

Account protection APIs are used to assess risk level, obtain recommendations, and provide feedback

Get recommendation

Get a risk recommendation for a client action reported to the SDK (via triggerActionEvent() call)

SecurityOAuth2: oauth2
Request
query Parameters
action_token
required
string
Default: "REPLACE_WITH_ACTION_TOKEN"

Action token returned by the SDK when the action was reported

user_id
string
Default: "REPLACE_WITH_USER_ID"

User identifier as sent to the SDK on the client-side

Responses
200

Recommendation

401

Invalid authorization

429

Rate limit reached

500

Unexpected error

get/recommendation
Request samples
curl -i -X GET \
  'https://api.riskid.security/v1/recommendation?action_token=REPLACE_WITH_ACTION_TOKEN&user_id=REPLACE_WITH_USER_ID' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d",
  • "issued_at": 1648028118123,
  • "recommendation": {
    },
  • "risk_score": 73.2,
  • "context": {
    },
  • "reasons": [
    ],
  • "preview_rule": {
    }
}

Create rule

Creates a new recommendation rule. Returns the rule_id used to reference the rule in subsequent requests.

SecurityOAuth2: oauth2
Request
Request Body schema: application/json
name
string

Name of the recommendation rule. Must be unique across the tenant. Auto generated if not provided.

priority
required
integer [ 1 .. 1000 ]

Priority of the recommendation rule, which determines the order in which rules are evaluated. Rules are evaluated from smallest to biggest priority value and only the first rule to match will apply. Priority value must be unique.

required
ip_cidrs (object) or device_ids (object) or user_ids (object) or country_codes (object) or browser_names (object) or os_versions (object) (matcher)

Activity field matcher. Only one matcher can be defined per rule.

recommendation
required
string (rule_recommendation_type)

Recommendation type

Enum: "CHALLENGE" "DENY" "TRUST"
enabled
required
boolean

Whether or not the rule will be evaluated

mode
required
string (rule_mode)

Allows you to simulate a rule and evaluate its impact before releasing it to production. The simulation occurs each time a recommendation is requested. If a preview rule matches the request (meaning, its priority is higher than all matching rules), the response will include this preview rule and what the recommendation would have been if all rules were in production.

Enum: "PREVIEW" "PRODUCTION"
Responses
201

Rule created successfully

400

Bad request

401

Invalid authorization

409

Unique field collision

500

Internal error

post/recommendation/rules
Request samples
application/json
{
  • "name": "Block risky countries",
  • "priority": 10,
  • "matcher": {
    },
  • "recommendation": "CHALLENGE",
  • "enabled": true,
  • "mode": "PREVIEW"
}
Response samples
application/json
{
  • "message": "string",
  • "rule_id": "string"
}

Get all rules

Retrieves a list of all recommendation rules

SecurityOAuth2: oauth2
Responses
200

Rules retrieved successfully

400

Bad request

401

Invalid authorization

500

Internal error

get/recommendation/rules
Request samples
curl -i -X GET \
  https://api.riskid.security/v1/recommendation/rules \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "data": [
    ]
}

Get rule by ID

Retrieves a specific recommendation rule by its ID

SecurityOAuth2: oauth2
Request
path Parameters
rule_id
required
string

ID of the recommendation rule

Responses
200

Rule retrieved successfully

400

Bad request

401

Invalid authorization

404

Not found

500

Internal error

get/recommendation/rules/{rule_id}
Request samples
curl -i -X GET \
  'https://api.riskid.security/v1/recommendation/rules/{rule_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "id": "string",
  • "data": {
    }
}

Update rule by ID

Updates a specific recommendation rule

SecurityOAuth2: oauth2
Request
path Parameters
rule_id
required
string

ID of the recommendation rule

Request Body schema: application/json
name
string

Name of the recommendation rule. Must be unique across the tenant. Auto generated if not provided.

priority
required
integer [ 1 .. 1000 ]

Priority of the recommendation rule, which determines the order in which rules are evaluated. Rules are evaluated from smallest to biggest priority value and only the first rule to match will apply. Priority value must be unique.

required
ip_cidrs (object) or device_ids (object) or user_ids (object) or country_codes (object) or browser_names (object) or os_versions (object) (matcher)

Activity field matcher. Only one matcher can be defined per rule.

recommendation
required
string (rule_recommendation_type)

Recommendation type

Enum: "CHALLENGE" "DENY" "TRUST"
enabled
required
boolean

Whether or not the rule will be evaluated

mode
required
string (rule_mode)

Allows you to simulate a rule and evaluate its impact before releasing it to production. The simulation occurs each time a recommendation is requested. If a preview rule matches the request (meaning, its priority is higher than all matching rules), the response will include this preview rule and what the recommendation would have been if all rules were in production.

Enum: "PREVIEW" "PRODUCTION"
Responses
200

Rule updated successfully

400

Bad request

401

Invalid authorization

404

Not found

500

Internal error

put/recommendation/rules/{rule_id}
Request samples
application/json
{
  • "name": "Block risky countries",
  • "priority": 10,
  • "matcher": {
    },
  • "recommendation": "CHALLENGE",
  • "enabled": true,
  • "mode": "PREVIEW"
}
Response samples
application/json
{
  • "message": "string"
}

Delete rule by ID

Deletes a specific recommendation rule. Note that you can also disable rules if needed using the enabled rule attribute.

SecurityOAuth2: oauth2
Request
path Parameters
rule_id
required
string

ID of the recommendation rule

Responses
200

Rule updated successfully

400

Bad request

401

Invalid authorization

404

Not found

500

Internal error

delete/recommendation/rules/{rule_id}
Request samples
curl -i -X DELETE \
  'https://api.riskid.security/v1/recommendation/rules/{rule_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "message": "string"
}