Direct Authentication API

If your company has an appropriate agreement with WingCash, you may use the direct authentication API. This API allows you to have maximum control over your users’ experience when signing up or logging in. Your users will not even need to know about WingCash.

These API calls are built around the concept of an authentication attempt (abbreviated “aa”). Users create an authentication attempt when they want to sign in, sign up, reset their password, or accept an invitation to sign up. The client interacts repeatedly with that authentication attempt until authentication completes. The client should be flexible: sometimes people start a sign-up attempt using credentials already registered to a user, in which case the client should let that user sign in rather than sign up. The Authentication Attempt Decision Tree helps client code choose which interaction is most optimal after responses from API calls.

Authentication API Rules

To use API calls involved in user authentication, you must follow the following rules.

  • You must not save or store user passwords anywhere or in any form. (Note: you may store and use device-specific passwords for biometric authentication; see POST /wallet/set-device-password.) When users provide their password to you, the only things you are permitted to do with that password are (1) show the user a password strength meter using client-side code (without transmitting the password to any server), (2) verify the password meets requirements such as the 8 character minimum length, and (3) transmit the password to WingCash for authentication.
  • WingCash communicates directly with the user using email and SMS to provide private access codes. You must not intercept that direct communication. You may provide templates for the format of the communication.
  • You must not keep user sessions alive except when the user (a human, not a program or device) is actively interacting with your software.
  • You must not initiate cash transfers except (1) under the user’s direction at the time of the transfer, or (2) using the WingCash API to configure scheduled transfers.
  • You may store users’ email addresses and phone numbers, but you must understand that users’ contact information may change through external means without notifying you.

WingCash Secret Authentication

Some direct authentication API calls require a special Authorization header containing a temporary secret. WingCash provides a temporary secret for direct authentication processes using the secret attribute of an AuthnResult object. When calling APIs that require the secret, the client must set the Authorization header based on that secret. The value of the Authorization header is of the following form:

wingcash secret="SECRET-HERE"

In other words, if the secret is 2345, subsequent authentication API calls for the same authentication attempt must include the following header:

Authorization: wingcash secret="2345"

WingCash Basic App Authentication

Some API calls require a special Authorization header that authenticates the app. Use HTTP Basic authentication, where the username and password are the client ID and client secret, respectively, assigned to the app.

If you need to construct the Authorization header yourself, use the standard Basic authentication encoding: join the client ID and client secret using a colon, encode in UTF-8, encode in standard base 64, and prefix the result with the word “Basic” and a space character. Set that as the value of the Authorization header.

Because client secrets must never be exposed to users (or users’ web browsers or mobile devices), you must call APIs that require basic app authentication using a server app rather than a web browser or a mobile device. Your users may send an invitation using a web browser or mobile device, of course, but your app’s front end must call your own back end server app, which calls the WingCash API in turn.

Start an Authentication Attempt

POST /aa/signup
POST /aa/signin
POST /aa/reset
POST /aa/accept

These four API calls start an authentication attempt, each with a different intent. The signup call is for creating a wallet, the signin call is for accessing an existing wallet, the reset call is for resetting a forgotten password, and the accept call is for accepting an invitation.

If the API call is successful, the client code should follow the Authentication Attempt Decision Tree to choose the next interaction with the user. The next interaction after starting an authentication attempt is usually a confirmation code entry view, but sometimes the user is reusing a known device and no code entry is necessary. Use the documented decision tree to avoid user interaction bugs.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • client_id (string) – The client_id assigned by WingCash to the app calling this API. See Create a WingCash App.
  • device_name (string) – Optional. The name of the device calling this API. If not provided, the device name will be derived from the User-Agent HTTP header.
  • device_uuid (string) – A UUID for the device. A randomly generated UUID is acceptable. The UUID should be persisted on the device and reused for future direct authentication API calls. Limited to 36 characters.
  • login (string) – The email address, phone number, or username provided by the user.
  • flow_subtype (string) – An optional short code that identifies which kind of process the user initiated. Clients may use this field as they see fit.
  • countries ([string]) – An array of country codes to use for interpreting the login field if a phone number was provided. Internally, WingCash converts all phone numbers to standard international format; this field determines which formats it will attempt. Defaults to ['US'].
  • password (string) – The user-supplied password. Required for the POST /aa/signin API call. Do not provide this parameter for the POST /aa/signup, POST /aa/reset, or POST /aa/accept API calls.
  • invite_id (string) – The ID of the invitation being accepted. Required for the POST /aa/accept API call.
  • trust30 (bool) – If this optional field is set to true, and the user authenticates successfully, WingCash will trust the device as one of the user’s authentication factors for 30 days. Another factor (such as the user’s password) is still required for future authentication. This does not affect the user’s session timeout. Never enable this option on shared or public computers. This option is intended for use only on personal mobile devices.
  • g-recaptcha-response (string) – Conveys the response provided by the invisible ReCAPTCHA widget. This field is required for POST /aa/signin calls when WingCash detects excessive attempts to guess passwords or authentication codes. This field is currently ignored by the POST /aa/signup, POST /aa/reset, and POST /aa/accept API calls.
Status Codes:

UID Authentication

POST /aa/(string: id)/auth-uid

Receive a code that validates the user’s control of a UID. The client calls this API after the user enters a code in response to an AuthnResult that requests code entry.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • factor_id (string) – The factor_id provided by WingCash in the AuthnResult JSON object.
  • code (string) – The code entered by the user.
  • g-recaptcha-response (string) – Conveys the response provided by the invisible ReCAPTCHA widget. This field is required when WingCash detects excessive attempts to guess passwords or authentication codes.
Status Codes:

Password Authentication

POST /aa/(string: id)/auth-password

Receive the user’s password for authentication. The client calls this API after the user enters a password in response to an AuthnResult that requests a password.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • password (string) – The code entered by the user.
  • g-recaptcha-response (string) – Conveys the response provided by the invisible ReCAPTCHA widget. This field is required when WingCash detects excessive attempts to guess passwords or authentication codes.
Status Codes:

Add Another Factor

POST /aa/(string: id)/add-factor

Begin adding another factor to this authentication attempt. The client calls this API after the user enters a login name in response to an AuthnResult that indicates another authentication factor is needed.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • login (string) – The email address, phone number, or username provided by the user.
  • countries ([string]) – An array of country codes to use for interpreting the login field if a phone number was provided. Internally, WingCash converts all phone numbers to standard international format; this field determines which formats it will attempt. Defaults to ['US'].
Status Codes:

Set Signup Data

POST /aa/(string: id)/set-signup-data

Record the user’s name and/or password for signup.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • first_name (string) – Optional. The user’s first name. If the first_name is provided, the last_name must also be provided.
  • last_name (string) – Optional. The user’s last name.
  • password (string) – Optional. The user’s new password. The client should help the user avoid typing errors by either asking the user to type the password twice and verifying the fields match, or by revealing the password to the user.
Status Codes:

Finish Signing Up

POST /aa/(string: id)/signup-finish

Finish the sign-up process. The user must already be fully authenticated using multiple factors.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • agreed (bool) – Must be True. Indicates the user agreed to the terms and conditions.
Status Codes:
  • 200 OK – Successful. The response body is an AuthnResult JSON object that should contain the token and profile objects.
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 410 Gone – The authentication attempt has expired or is no longer available due to excessive code failures.

Finish Password Reset

POST /aa/(string: id)/reset-password

Finish changing the user’s password. The user must already be fully authenticated using multiple factors.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • password (string) – Required. The user’s new password. The client should help the user avoid typing errors by either asking the user to type the password twice and verifying the fields match, or by revealing the password to the user.
Status Codes:
  • 200 OK – Successful. The response body is an AuthnResult JSON object that should contain the token and profile objects.
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 410 Gone – The authentication attempt has expired or is no longer available due to excessive code failures.

Send an Invitation

POST /ai/invite

Send an invitation to an individual to join your service. The recipient of the invitation will receive an email and/or SMS that directs the recipient to an URL of your choosing. The URL contains an invite ID and an authentication code that validates the recipient’s email address or phone number. When the recipient visits the URL, the recipient either creates a wallet or signs in to an existing wallet.

WingCash protects this API call using your app credentials, but does not protect it with a permission. Your app must ensure only permitted users can call it.

Note: Unlike most WingCash API calls, this call requires WingCash Basic App Authentication.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • first_name (string) – Required string. The new member’s first name. The first name must be no longer than 50 characters and must start with a letter. Certain Unicode symbols (such as 0x2000 through 0x2fff) are disallowed. Do not use the name of a business as the first or last name.
  • last_name (string) – Required string. The new member’s last name. The last name must be no longer than 50 characters and must start with a letter. Certain Unicode symbols (such as 0x2000 through 0x2fff) are disallowed. Do not use the name of a business as the first or last name.
  • email (string) – Optional string. Specifies the invitation recipient’s email address. Limited to 100 characters. Either email or phone is required. Note that the invitation recipient may choose a different email address while signing up or signing in.
  • phone (string) – Optional string. Specifies the invitation recipient’s SMS-compatible phone number, in either a country-specific format or the international E.164 format. Limited to 100 characters. Either email or phone is required. Note that the invitation recipient may choose a different phone number while signing up or signing in.
  • countries (string) – Optional string containing two-letter country codes, separated by whitespace. WingCash consults the country list when parsing the phone number in the phone field. Defaults to US if not specified.
  • ext_id (string) – Optional string containing app-specific information about this invitation. This usually contains an invitation ID, but may contain up to 1024 characters. The ext_id will be provided to the app when the app calls GET /wallet/finish-invite.
  • url_template (string) –

    Required string. Provides the template for the URL to be sent to the invitation recipient in email and SMS. When the user visits the final URL, your app should query the state of the invitation at WingCash and show a user interface for completing the invitation process. Here is an example URL template:

    https://example.com/invite/INVITE_ID/CODE

    The following variables are available for use in URL templates:

    • INVITE_ID: A unique identifier of the invitation.
    • CODE: A random code that authenticates the channel the recipient used to receive the invite.
    • DELIVERY_ID: A random identifier that helps identify which channel (email or phone) the recipient used to receive the invite.
    • EXT_ID: The ext_id provided by the app when creating the invitation.

    It is sufficient to use only INVITE_ID and CODE in the URL template.

  • sender_name (string) – Required string containing the name of the person sending the invitation.
  • sender_url (string) – Optional string containing an URL for information about the sender of the invitation.
  • sender_image_url (string) – Optional string containing an URL of an image of the sender of the invitation.
  • org_name (string) – Optional string containing the name of the organization the invitation sender represents.
  • org_url (string) – Optional string containing an URL for information about the organization specified in org_name.
  • org_image_url (string) – Optional string containing an URL of an image of the organization specified in org_name.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object containing id, the ID of the invitation.

    If you’re using a sandbox or test instance of WingCash, you may also receive revealed_codes, a list of strings that reveal the codes sent by email, SMS, or another communication channel, for testing purposes.

  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.

Get the State of an Invitation

GET /ai/(string: invite_id)

Lets the recipient of an invitation get information about the invitation. Requires an authentication code that only the recipient should have.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object containing:

    • id
      The ID of the invitation.
    • first_name
    • last_name
    • sender_name
    • sender_url
    • sender_image_url
    • org_name
    • org_url
    • org_image_url
    • failures
      The number of times someone has tried to authenticate through this invitation and failed.
    • email
      The email address of the invitation recipient, as provided by the sender, if any.
    • is_personal
      A boolean value that is true if the email appears to contain a personal email address rather than a corporate email address. This is only a heuristic.
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 410 Gone – The invitation has expired or is no longer available due to excessive code failures.

Re-send an Invitation

POST /ai/(string: invite_id)/reinvite

Re-send the invitation messages to a recipient. Must be called by the same app (but not necessarily by the same user) that initiated the invitation. The app may provide updated invitation information.

Note: Unlike most WingCash API calls, this call requires WingCash Basic App Authentication.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • email (string) – Optional string. If either an email address or phone number is provided, WingCash will send the updated invitation to the new email address and/or phone number. If neither an email address nor phone number is provided, WingCash will send the updated invitation to all the email addresses and phone numbers previously specified for this invitation.
  • phone (string) – Optional string. See the documentation of the email field.
  • first_name (string) – Optional string.
  • last_name (string) – Optional string.
  • countries (string) – Optional string.
  • ext_id (string) – Optional string.
  • url_template (string) – Optional string.
  • sender_name (string) – Optional string.
  • sender_url (string) – Optional string.
  • sender_image_url (string) – Optional string.
  • org_name (string) – Optional string.
  • org_url (string) – Optional string.
  • org_image_url (string) – Optional string.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object containing id, the ID of the invitation.

    If you’re using a sandbox or test instance of WingCash, you may also receive revealed_codes, a list of strings that reveal the codes sent by email, SMS, or another communication channel, for testing purposes.

  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 410 Gone – The invitation has expired or is no longer available due to excessive code failures.

Expire an Invitation

POST /ai/(string: invite_id)/expire

Expire an invitation for a recipient immediately. No messages will be sent. The recipient will no longer be able to accept the invitation.

Note: Unlike most WingCash API calls, this call requires WingCash Basic App Authentication.

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
Status Codes:

Finish Receiving an Invitation

GET /wallet/finish-invite

This is a clone of GET /wallet/info, except that it adds the invite_id and ext_id attributes so your service can apply service-specific policies to the recipient such as adding them to an organization.

Call this when the invited user has finished authenticating. You should access this view using server-side software (rather than a browser page or mobile app) to prevent manipulation by the user.

This call also has a side effect of expiring the invitation immediately. When the invitation expires, you can call this view again and get the same results as before, but users can’t use the invitation to authenticate anymore.

Permission Required:
 

view_wallet. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    profile
    A ProfileDetail object describing the authenticated profile.
    related
    A list of Profile or ProfileDetail objects providing info about profiles linked with the authenticated profile. Includes profiles managed by the authenticated personal profile and featured profiles. Profiles managed by the authenticated personal profile are represented as ProfileDetail objects.
    invite_id
    The WingCash ID of the invitation the recipient used to authenticate on your app.
    ext_id
    The external invitation ID or information string provided by your app in the POST /ai/invite API call, or null.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object.
  • 401 Unauthorized – The access token is missing or not valid. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function.

Get the ReCAPTCHA sitekey

GET /aa/recaptcha_invisible_sitekey

Get the site key to use for the invisible ReCAPTCHA widget.

Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    sitekey
    The site key to use when creating the invisible ReCAPTCHA widget.
    captcha_bypass
    In development and test environments, WingCash may provide a captcha_bypass string value that the app can use as the g-recaptcha-response in place of a real ReCAPTCHA solution. In production environments, this field does not exist.

Trust the Device For 30 Days

POST /aa/(string: id)/set-trust

Enable or disable the option to trust the device for 30 days. The setting only takes effect when authentication completes (when completed_mfa is true).

Request Headers:
 
Request JSON Object:
 
  • version (string) – Optional. If provided, must be 1.
  • trust30 (bool) – Required boolean value. Set to true if the user trusts the device for 30 days.
Status Codes:
  • 200 OK – Successful. The response body is an empty JSON object.
  • 400 Bad Request – A parameter was invalid or incorrect. The response body contains an InvalidRequest or CaptchaRequired object.
  • 410 Gone – The authentication attempt has expired or is no longer available due to excessive code failures.