---
title: "Login Attempt Request"
method: POST
path: "/login"
tags: ["Customer Actions"]
---

# Login Attempt Request

`POST /login`

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.

## Headers

- `x-riskified-shop-domain` string, required
- `x-riskified-hmac-sha256` string, required
- `content_type` 'application/json', required
- `accept` 'application/vnd.riskified.com; version=2', required

## Request body

- LoginAction
  - `customer_id` string — **(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').
  - `email` string — **(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).
  - `login_status` LoginStatus, required — An object containing details of the customer's login attempt.
    - `login_status_type` 'success' | 'failure', required — Indicates the success or failure of a login attempt. **Possible values:** - `success`: Login was successful - `failure`: Login failed
    - `failure_reason` 'wrong password' | 'captcha' | 'disabled account' | 'nonexistent account' | 'other' — **(Conditional Requirement)** The reason for the unsuccessful login, required if `login_status_type` = `'failure'`. **Possible values:** - `wrong password`: When login failed with wrong password - `captcha`: When login failed at Captcha or reCaptcha - `disabled account`: When login failed due to the account being logically deleted (disabled) - `nonexistent account`: When login failed because account never exists at merchant - `other`: When login failed due to other reasons such as "account is locked"
  - `client_details` ClientDetails, required — An object containing technical information regarding the customer’s browsing session
    - `user_agent` string, required — The full User-Agent sent from the client.
    - `accept_language` string, required — List of two-letter language codes sent from the client.
  - `session_details` SessionDetails, required — An object containing basic information regarding the session. Session data points, such as `cart_token`, `browser_ip`, and `user_agent`, should be those associated with values at the time of user's login request - **before** the authentication result is available.
    - `cart_token` string, required — The session id at the time that the user is on the login webpage or started password reset, prior to authentication attempt. Must match the `session_details.cart_token` value set by the Beacon JavaScript snippet. For standard integrations, this value is automatically generated by Beacon. For merchants who manage their own sessions, the same session ID must be passed to both the Beacon and this field. Must remain consistent throughout a purchase flow. Max 100 characters.
    - `browser_ip` string, required — The customer's browser IP address during the session.
    - `created_at` string, required — The date and time (ISO8601) of the session.
    - `source` 'desktop_web' | 'mobile_web' | 'web' | 'mobile_app' | 'other', required — The platform that the session originated from. **Possible values:** - `desktop_web`: Session originated on the website, using a desktop device - `mobile_web`: Session originated on the mobile website, using a mobile device - `web`: Session originated on the website, with no available info about the type of device used - `mobile_app`: Session originated on the mobile app, using a mobile device - `other`: The session's origin is unknown
    - `device_id` string — **(Conditional Requirement)** Required for mobile applications. The mobile device identifier, which corresponds to a value extracted via the Riskified mobile beacon SDK.
    - `referring_site` string — **(Strongly Recommended)** The webpage from which the customer accessed the shop. Domain level is enough, and usually set the shop_url provided by Riskified. In case you have several sites may be used by different population, set different url per the scenario (e.g. regular ec-site: www.shop-regular.com, employee ec-site: www.shop-employee.com)
  - `customer_created_at` string, 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_login` boolean — Indicates whether this login was made by entering the user’s credentials or not (“remember me” - cookie usage)
  - `username` string — **(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_checkout` boolean — Indicates whether the login attempt was made at checkout.
  - `challenge_redirect_url` string — **(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_url` string — 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_language` string — The 2 letter code (ISO 639-1) to indicate the language the user has selected for merchant site content browsing and communications.
  - `vendor_name` string — 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`

## Response `200`

Successful operation

- LoginActionResponse — The response to the login action request.
  - `login_id` string, 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

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found
- `429` — Too many requests
- `500` — Contact Riskified support
- `504` — Temporary error, please retry

---

[API](https://skmtc.dev/riskified/apis/chargeback-guarantee.md) · [All operations](https://skmtc.dev/riskified/apis/chargeback-guarantee/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/riskified/chargeback-guarantee/revisions/2b7df5bce861/schema)