Authentication

Bridge supports three main authentication methods. Each pathway requires different credentials and different forms of interaction from the user, so you will want to evaluate the approach that is best for your onboarding experience.

Email and Password Authentication

For backend system accounts and some studies, users can sign up with an email address and a password they themselves supply.

While apps have in the past cached these credentials to sign the user back into the system on session expiration, the reauthentication token in the session can now be used to renew the session with no further credentials.

Email/Password Sign-Up

On sign up for the study, the following steps must be executed:

  1. The user signs up for an account, entering an email address and password as part of the SignUp payload and the sign-up API. Your app should verify a password has been entered, otherwise the server will assume this account will be authenticated using the email-only pathway;
  2. The server will send an email with a link to verify the email address. This link does not need to be intercepted by the app, and the link can be opened in any web browser on any device. The link contains a one-time token to verify control of the email address;

Email/Password Sign-In

After verifying their email address, the user must manually sign in to the application. They can sign in using their email and password using the SignIn payload and the sign-in API. This request, when successful, returns a session. The status code will either be 200 or 412 (Precondition Required) if the user must consent to research in order to use the API.

See reauthentication below for how to refresh a session once it expires, without user intervention.

Note: It is possible to reset the password on an account with no password, and set a password for that account. That account will then be able to sign in with an email and password, if there is any way to do so in your app or another user interface. This is most likely to come up for developers who use their email address both for a test account in the app, and to sign in to our administrative interface, the Bridge Study Manager.

Email-Only Authentication

Users can authenticate using only their email address. The steps for this form of authentication are as follows:

Email-Only Sign-Up

On sign up for the study, the following steps must be executed:

  1. The user signs up for an account, entering an email address (but no password) as part of the SignUp payload using the sign-up API;
  2. The server will send an email with a link to verify the address and sign in to the application;
  3. If the user clicks the link on the phone. The link should be captured as a "deep link" by the app. The link contains a query string portion that has a token parameter the app should extract from the URL;
  4. The app must send the following information to the server:
    • email—the user's email address;
    • study—the study identifier of the study;
    • token—the token that was sent via email.
  5. The app sends this information to authenticate using the email sign in API and the SignIn playload:
  6. If the token is valid and it has been submitted within 5 minutes of being generated by the server, it will verify the email address if it hasn't been verified, and a UserSessionInfo is returned to the app, with the same status codes as described for email/password authentication.

If the user clicks the link on another device, you will need to capture the link on your website with an explanation that the link should be used via email on the phone.

See reauthentication below for how to refresh a session once it expires.

Email-Only Sign-In

After sign-up, when the user needs to sign-in again due to a session expiration, the app will either need to use the cached email address, or prompt for the email address, to trigger an email sign-in request. This sends an email as described from step #2 above.

Phone-Only Authentication

Users can authenticate using only their phone number. The steps for this form of authentication are as follows:

Phone-Only Sign-Up

On sign up for the study, the following steps must be executed:

  1. The user signs up for an account, entering a telephone number (but no password) as part of the SignUp payload using the sign-up API;
  2. The server will send an SMS message with a code to enter into your application;
  3. The user enters the code. The app must send the following information to the server:
    • phone—the user's phone number (the user many need to be prompted to enter the phone number, depending on the platform);
    • study—the study identifier of the study;
    • token—a string representation of the numeric code sent via SMS that must be passed back to the server to authenticate.
  4. The app sends this information back to the phone sign in API using the PhoneSignIn playload;
  5. If the token is valid and it has been submitted within 5 minutes of being generated by the server, it will verify the phone number if it hasn't been verified, and a UserSessionInfo is returned to the app, with the same status codes as described for email/password authentication.

See reauthentication below for how to refresh a session once it expires.

Phone-Only Sign-In

After sign-up, when the user needs to sign-in again due to a session expiration, the app will either need to use the cached phone number, or prompt for the number again, to trigger a phone sign-in request. This sends an SMS message as described from step #2 above.

Reauthentication

The UserSessionInfo payload returned by the sign in process includes a reauthToken that can be sent to the reauthentication endpoint. The token is a one-time token that will be replaced when it is used to generate a new session for the client (that session includes a new token in order to chain these requests indefinitely). In effect, the reauthToken is like an auto-generated password that avoids the need for users to sign in again once we establish their identity.

As long as the application holds on to this reauthentication token, it will not need to re-involve the user in authentication. If the app loses this token, it will have to sign in again using its preferred authentication channel. In the case of email/password credentials, the app may be able to cache the credentials and sign in again without prompting the user. In the case of email-only and phone-only authentication, the app will need to involve the user.

Adding additional credentials

It is useful and important to collect further credentials than the minimum necessary to sign in. For example, if you prompt your user to enter only an email address, you may subsequently collect a telephone number, or password. The same is true of other credentials.

Additional credentials will make it possible for the user to authenticate with Bridge if a phone number is re-assigned (there are even rare examples where Yahoo and Microsoft have re-assigned email addresses that they did not believe were in use). In this situation, the user will want to change these credentials, but they will need another pathway to authenticate in order to make this change. Your app will also need to provide support for that alternative method of authentication.

Sign Out

When the sign out API is called, the client should include the Bridge-Session token with the current session token. This will delete the session and invalidate the reauthentication token.

A Note on Sign Up Behavior

On signing up for an account with Bridge, if the user provides an email address and email verification is enabled (emailVerificationEnabled), an email will be sent to the address with a link that will verify and activate the account. If your application exclusively uses phone- or email-based sign in, you may wish to disable this verification email since authenticating via either of these channels will automatically enable the account.