AuthnResult

WingCash returns an AuthnResult from several Direct Authentication API calls. The client should use the content of the AuthnResult to choose which interaction the user should complete next in order to finish signing up or signing in. Not all attributes are present in every interaction.

Initial Attributes

These attributes are included in the result of API calls that start a new authentication attempt.

attempt_path

The path inside the WingCash API for updating or accessing the new authentication attempt. It looks like /aa/<attempt_id>.

secret

A string that authenticates the user’s device for the duration of the authentication attempt. The client should not share this string with other devices. In subsequent authentication API calls, the client must set the HTTP Authorization header based on this secret. See WingCash Secret Authentication.

Code Entry Attributes

These attributes are provided when the user needs to enter a code sent to them through email, SMS, or another mechanism.

factor_id

An opaque string that identifies which factor the user should attempt to authenticate. The factor_id changes for each authentication attempt.

code_length

The length of the code the user should enter. The length is currently either 6 or 9 digits depending on the authentication flow type, but WingCash may expand the code length if necessary.

unauthenticated

A mapping of the UID strings the user is currently attempting to authenticate. Maps the UID to original and country. original is the UID in a human format, such as a formatted phone number or an email address with capitalization.

revealed_codes

In WingCash development sandboxes and testing environments, this is a list of human-readable strings that reveal the authentication codes sent to the user through email, SMS, or another channel. This allows testers to skip the communication channel. In production, this attribute does not exist.

State Attributes

These attributes reveal the progress of the authentication attempt and whether the user has successfully completed authentication.

captcha_required

A boolean value indicating whether certain sensitive API calls currently require a valid g-recaptcha-response field value. WingCash uses g-recaptcha-response as evidence that a human initiated the API call.

authenticated

A mapping of the UID strings the user has successfully authenticated as part of this authentication attempt. Maps the UID to original, country, and strong. original is the UID in a human format, such as a formatted phone number or an email address with capitalization. strong is a boolean value indicating whether the authentication mechanism was considered strong.

completed_mfa

Boolean: true if the user has authenticated enough factors to complete this authentication attempt. If the user already has a profile_id, the AuthnResult will have the token and profile attributes listed in the Final Attributes section below.

WingCash considers multi-factor authentication complete when the user has authenticated two factors of different types. The possible factor types include email, phone, and device ID. At least one of the factors must use strong authentication in order to authenticate any profile that existed before this authentication attempt. WingCash considers passwords and 9 digit user-entered codes to be strong authentication. 6 digit codes are considered to be weak authentication.

profile_id

The WingCash profile ID (wallet ID) connected with any authentication factor the user has already authenticated as part of this authentication attempt.

profile_title

The title of the profile given by profile_id.

signup

If this authentication attempt is a signup flow, this attribute is an object containing first_name, last_name, name_checked (boolean), and has_password (boolean). name_checked is true if the first and last name pass the WingCash name validity tests (such as not containing any Unicode symbols, etc.) This attribute is null for other authentication attempt flows.

invite_id

If this authentication attempt is an accept flow, this attribute contains the invite ID that started the attempt. Otherwise this attribute is null.

trust30

A boolean value indicating whether this authentication attempt will label the client device as trusted once the authentication completes successfully.

Final Attributes

Once the user with a wallet completes authentication, the AuthnResult has the following attributes.

token

An AccessTokenInfo object.

profile

The ProfileDetail for the newly authenticated user.

Authentication Attempt Decision Tree

When your code receives an AuthnResult, you should use code similar to the following to decide what to show the user next:

var next_interaction;

if (!result.completed_mfa) {
    if (!result.factor_id && !result.profile_id) {
        // Request an authentication factor. The user should input
        // an email address or phone number.
        next_interaction = 'add-factor';
        // After the user interaction, your code should call:
        // /aa/(string:id)/add-factor
    } else if (result.factor_id) {
        // Ask the user to enter a code sent to them by WingCash.
        next_interaction = 'enter-code';
        // After the user interaction, your code should call:
        // /aa/(string:id)/auth-uid
    } else {
        // Ask the existing user to sign in using their password.
        next_interaction = 'sign-in';
        // After the user interaction, your code should call:
        // /aa/(string:id)/auth-password
    }
} else if (!result.profile_id) {
    if (result.signup && result.signup.has_password) {
        // Ask the user to accept the terms of service and privacy policy.
        next_interaction = 'agreement';
        // After the user interaction, your code should call:
        // /aa/(string:id)/signup-finish
    } else if (result.signup && result.signup.name_checked) {
        // Ask the user to set a password.
        next_interaction = 'set-password';
        // After the user interaction, your code should call:
        // /aa/(string:id)/set-signup-data
    } else {
        // Request the user's name.
        next_interaction = 'set-personal-name';
        // After the user interaction, your code should call:
        // /aa/(string:id)/set-signup-data
    }
} else {
    // The authentication flow is complete.
    next_interaction = 'authenticated';
    // The access token you need for most WingCash API calls
    // is now available as ``result.token.access_token``.
    //
    // If this is a password reset flow, you should prompt
    // the user for a new password and call:
    // /aa/(string:id)/reset-password
    //
    // If the user accepted an invitation, you should call:
    // /wallet/finish-invite
}

To optimize the user experience and avoid unnecessary user interactions and server round trips, your code should avoid calling the direct authentication API calls in an unchanging sequence. Ideally, your code should contain an implementation of this decision tree. Your code should be constructed as follows:

1. Start an authentication attempt with POST /aa/signup, POST /aa/signin, POST /aa/reset, or POST /aa/accept. Receive an AuthnResult.
2. Based on the most recent AuthnResult you received, your implementation of the decision tree should decide which interaction to perform with the user. For example, if the next_interaction as specified by the tree is enter-code, you should show a screen or dialog that asks the user to enter a code they received by email or SMS.
3. At the end of the user interaction, call the API specified by the decision tree comments.
4. If the API call succeeds, you will receive an updated AuthnResult; you should then loop back to step 2. If the password was incorrect or some other error occurred, WingCash will respond with an InvalidRequest. You should display the error to the user and repeat the user interaction until it succeeds.