User Authentication with OAuth

We use a variation of OAuth 2.0 for user authentication. This means that to perform any user actions, or to make any changes to a user, you need to supply a valid OAuth Key in the header field of the API request. Read more about what to include in our headers in API Initialization Reference.

Issuing OAuth Key

An OAuth key is a token representing a user's identity. See Issue OAuth Key for more information on creating an OAuth key. The OAuth key will be returned in the response of this API call and will be used in the headers of subsequent API calls to allow users to perform other actions.

OAuth Key Expiration Times

OAuth keys currently expire after 2 hours. After an OAuth key expires, you can use a refresh token to generate a new OAuth Key. Please remember to take OAuth key expiration into account when building out your application.

Generating New OAuth Keys with Refresh Tokens

To generate a new OAuth key, you can use a refresh token. These tokens expire after ten uses and update periodically. We manage this complexity for you. See Issue OAuth Key for more information. Refresh tokens expire after ten uses.

Retrieving OAuth Key for a User

To get the OAuth key for a new user, find refresh_token from the Create User w/ KYC API call or the Create User w/o KYC API call. The most recent refresh token for an existing user can also be retrieved from View User API call.

Recommended Flow For Authenticating an Existing User

1. Perform View User API Call (highly recommended for easiest development flow)

• When you need a new OAuth key to perform some user action(s), we recommend performing a View User call so that you can grab a new refresh_token from the response.

2. ###Issue OAuth Key

• Using the newly acquired refresh token, you should now be able to issue a new OAuth key for the user.

3. ###Use Your OAuth Key to Perform User Actions

• You should be able to perform user actions as long as your OAuth Key remains active (i.e. until it expires after 2 hours).
• Once your OAuth key expires, we recommend that you simply perform another View User API call to generate a new refresh token when needed (i.e. go back to Step 1 above).
  • Alternatively, you have the option to use a previously stored refresh token to generate a new OAuth key, but this option would require you to build additional logic into your user authentication process (e.g. to store the refresh token in your own database, keep track of the number of times you have used the refresh token, etc.).

New Devices

If you OAuth with a new device, you may need to Register New Fingerprint.

Device Fingerprint Authentication

Along with OAuth, we also use device fingerprints for authentication. Fingerprints are used to identify the device that is trying to access a user's information. You need to supply fingerprints when you create a user. The fingerprint supplied during the POST user creation is the registered fingerprint associated with the user.

Additionally, you can incorporate two-factor authentication ("2FA") into your user login process when your user connects with a different device. To do so, just supply the new, non-verified fingerprint. See Register New Fingerprint to register a new device fingerprint to the user account and use our two-factor authentication (2FA) security protocols.

If the user supplies a non-verified fingerprint during login, the user will be directed to the 2FA flow. We return the linked phone numbers in the API call response with key phone_numbers. You can let the user select the phone number from that list and then make the API call again by specifying the phone_number you want the 2FA to be sent. This will trigger the 2FA protocol and a PIN will be sent to the selected phone number. The user will be able to verify the device via this API call itself. You can supply validation_pin under the user object and the verification will be triggered. See Select 2FA Device and Verify 2FA PIN for more information.

🚧

Don't Want to Trigger 2FA? (NOT RECOMMENDED)

We strongly recommend using 2FA or some form of MFA within your authentication process.

If you do not want to use our 2FA, store the fingerprint used when creating the user and supply the fingerprint when performing actions with the user. This way the system will not detect a new device and no 2FAs will be triggered.

Alternatively, you can also pass a hashed version of your user_pk+client_id+client_secret. That way the value is still somewhat secret and you won't need to store a different fingerprint for each user.

Issuing a Public Key

To be able to use any UIaaS (UI as a Service) product, you need a public key. A public key is a token representing your client credentials. See Issue Public Key for more information. Public key expiration times are fairly short, so we recommend issuing a new key for each session.

We also recommend only issuing a public key with the scopes that are absolutely needed to make the UIaaS interface work. We will mention the scopes on every interface document for you so that it is easier to figure out.

Public Key Expiration Times

If you are issuing a public key with only CLIENT|CONTROLS as the scope, the public key would expire in 24 hours. Otherwise, public keys expire in 15 minutes.

Even if you are issuing a public key with just scope CLIENT|CONTROLS, we still recommend issuing a new public key for each session. In the future expiration times may be updated to be less than 24 hours.