ReachFive Developer Documentation

The Identity Fraud Protection (IFP) module analyzes login and signup attempts to detect suspicious IP behavior. When a suspicious IP is identified, it is flagged and blocked immediately.

Key capabilities include:

• Reducing the impact of credential stuffing attacks.
• Preventing bots from performing bulk signup requests.
• Blocking suspicious IPs immediately.
• Whitelisting trusted IPs to bypass protection policies.
• Automatic temporary suspension of accounts if a malicious IP successfully accesses an account (blocks password, OTP, Passkey, and SSO; social login remains usable).

The ReachFiveError object provides detailed information about failed requests. Key properties include:

• message: General error message.
• code: The HTTP status code or SDK error code.
• getErrorCode(): Returns the ErrorCode enumeration value.
• data: A ReachFiveApiError object containing:
  • errorUserMsg: A translated, user-friendly error message.
  • errorMessageKey: The technical error code.
  • errorDescription: The technical error message.
  • errorDetails: A list of ReachFiveApiErrorDetails mapping specific fields to error messages.

The idTokenPayload within the AuthResult object contains claims about the authenticated user. Key claims include:

• sub: Unique subject identifier.
• email / emailVerified: User's email and its verification status.
• givenName / familyName / name: User's first, last, and full name.
• gender: Allowed values are female, male, and other.
• auth_time: Time of authentication.
• newUser: Boolean indicating if the user is new.
• picture / profile: URLs to the user's image and profile.

The idTokenPayload within the AuthResult contains claims about the authenticated user, including:

• sub: Subject identifier
• name: Full name
• givenName: First name
• familyName: Last name/surname
• email: User email
• emailVerified: Boolean indicating if email is verified
• gender: female, male, or other
• birthdate: User birthdate
• locale: User locale
• picture: User profile picture URL
• newUser: Boolean indicating if the user is new
• auth_time: Time of authentication
• exp: Expiration time
• iat: Issued at time
• iss: Issuer

User-event webhooks allow you to trigger external URLs when specific user actions occur (e.g., sign-up or account deletion). Purse Identity supports two types of webhooks:

• Post-event webhooks: Triggered asynchronously after the event is processed. The API returns a response immediately, and the user is not blocked. This is the recommended type.
• Pre-event webhooks: Triggered before the event is processed. These are synchronous and can be used to send additional data or prevent the event from proceeding. They suspend the API response, so a timeout (default 10 seconds) is critical to prevent user blockage.

Pre-event Webhook Behavior on Failure:

• Continue processing: The event proceeds as if no webhook existed (may lead to unsynchronized data).
• Prevent processing: The event is blocked and an error is returned (ensures data consistency).

The ApiError object provides detailed information about a failed request, including:

• error: The main error message.
• errorId: Unique identifier for the error.
• errorUserMsg: A localized, user-friendly message (supports multiple languages including English, Spanish, French, German, Chinese, etc.).
• errorMessageKey: The key used for the error message.
• errorDescription: Technical details of the error.
• errorDetails: An array of FieldError objects containing the specific field, message, and code for validation errors.

The idTokenPayload within the AuthResult contains claims about the authenticated user. Common claims include:

• sub (string): Subject identifier.
• name (string): Full name of the user.
• givenName (string): First name.
• familyName (string): Last name/surname.
• email (string): User email address.
• emailVerified (boolean): Whether the email is verified.
• gender (string): Allowed values: female, male, other.
• birthdate (string): User's birthdate.
• locale (string): User's locale.
• picture (string): URL to the user's profile picture.
• newUser (boolean): Indicates if the user is new.
• iss (string): Issuer of the token.
• aud (string): Audience of the token.
• exp (number): Expiration timestamp.
• iat (number): Issued-at timestamp.

The ReachFiveError enum provides detailed information about failures during authentication and MFA processes.

• AuthCanceled: The user canceled the request, no passkey was found, or a concurrent web login interrupted the process.
• RequestError(apiError: ApiError): Occurs for Bad Request (HTTP 400) errors.
• AuthFailure(reason: String, apiError: ApiError?): Occurs primarily for Unauthorized (HTTP 401) errors.
• TechnicalError(reason: String, apiError: ApiError?): Occurs for Internal Server Errors (HTTP 500) or other internal failures.

The nested ApiError object contains errorUserMsg (a localized, user-friendly message), errorId, errorMessageKey, and errorDescription.