Sign in

v1

latestOpenAPI 3.0.02026-07-2417129274.8 KB
Customer Actions

Login Attempt Request

Login API is a synchronous POST-method API call.

API is triggered only for customer-initiated authentication requests, e.g., user tries to login to their account. It must not be called for authentications associated with:

  • New account registrations
  • Successful password resets
  • Silent logins

API is triggered regardless of success or failure. There is a login_status_type to indicate success/failure and failure_reason to indicate the reason.

Response:

  • decision field will be set as one of the following values: allow, notify, or challenge.
  • login_id field will show a Riskified-assigned identifier for the event.
post/login

Headers

x-riskified-shop-domainstring required
Example:merchant.example.com

The merchant shop domain registered with Riskified.

x-riskified-hmac-sha256string required
Example:b1946ac92492d2347c6235b4d2611184

Verification hash for the Request. Generated by performing an SHA256 encryption on the request's POST body and calculating the HMAC hash of the result using your Riskified authentication token. Please use UTF8 encoding.

content_type'application/json' required

As payloads are sent to Riskified in JSON format, value should be: application/json

accept'application/vnd.riskified.com; version=2' required

Specify the version of the API to target. For example, to target the latest version of the API, use the following: application/vnd.riskified.com; version=2

Request body

customer_idstring

(Conditional Requirement) A unique numeric identifier for the customer. customer_id should be null when login failes because of no customer account exisistent (e.g. failure_reason = 'nonexistent account').

emailstring

(Conditional Requirement) The email address used for the login attempt. It is required for successful logins. It is an optional field for failed logins (if username is provided).

customer_created_atstring date-time

(Conditional Requirement) Use if login_status_type = 'success'.

• The timestamp (ISO8601) of the initial registration of the customer's account in the merchant's systems.

• customer_created_at should be null for failed logins (login_status_type = 'failure') where the failure_reason = 'nonexistent account' or 'other'.

implicit_loginboolean

Indicates whether this login was made by entering the user’s credentials or not (“remember me” - cookie usage)

usernamestring

(Conditional Requirement) The username used for the login attempt. Username is an optional field for successful logins. It is a required field for failed logins (if no email address is provided).

login_at_checkoutboolean

Indicates whether the login attempt was made at checkout.

challenge_redirect_urlstring

(Conditional Requirement) URL to which customer will be redirected to upon taking action from the verification emails. It is only required for integrations that involve 'challenge' decisions. It will be the secure magic link, embedded in a user's challenge email 'it was me' prompt.

Note: mandatory for merchants using the challenge flow

account_recovery_urlstring

URL to which customer will be redirected to upon taking action from the verification emails to recover user account. It is used as redirect URL for 'it was not me' CTA in a user's notify/challenge email. However, merchant can also set fixed url for redirect in Riskified system instead of setting account_recovery_url in login request.

localization_languagestring

The 2 letter code (ISO 639-1) to indicate the language the user has selected for merchant site content browsing and communications.

vendor_namestring

The name of the affiliated partner or selling vendor.

social_login_type'facebook' | 'google' | 'linkedin' | 'twitter' | 'yahoo' | 'other'

In case the user used a social network to log in, send one of the following values.

Possible values:

  • facebook
  • google
  • linkedin
  • twitter
  • yahoo
  • other

Example request

{
  "customer_id": "207119551",
  "customer_created_at": "2019-09-12T14:04:50-05:00",
  "implicit_login": false,
  "username": "donnie7",
  "email": "bob.norman@hostmail.com",
  "login_at_checkout": true,
  "login_status": {
    "login_status_type": "success"
  },
  "client_details": {
    "accept_language": "en-CA",
    "user_agent": "Mozilla/5.0 (CFNetwork/548.0.3 Darwin/11.2.0)"
  },
  "session_details": {
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "browser_ip": "111.111.111.111",
    "created_at": "2025-11-18T13:36:50-04:00",
    "source": "mobile_app",
    "device_id": "01234567-89ABCDEF-01234567-89ABCDEF",
    "referring_site": "http://www.nba.com/"
  }
}

Response

Successful operation

login_idstring required

Riskified-assigned identifier for the event.

decision'allow' | 'notify' | 'challenge' required

The decision made by Riskified regarding the login attempt.

Possible values:

  • allow: Login is approved
  • notify: Login is allowed but customer should be notified
  • challenge: Additional verification required before allowing login