Starting April 1st, 2017 select API endpoints require an MFA (Multi-Factor Authentication) Trusted Session to use. An MFA Trusted Session is an additional security requirement to protect your account and it requires that your API user account has a registered mobile phone number as their primary or backup phone in their Bill.com user profile. MFA Setup can currently only be completed through our web application.
MFA Protected Endpoints
The following endpoints require an MFA Trusted Session to use:
Note: Developers who joined the Developer Program and used these endpoints prior to March 31st, 2017 will not require an MFA Trusted Session and can continue using these endpoints as they normally would.
An API session can be marked trusted in two ways:
deviceIdwhen calling Login. If these parameters are supplied they will be checked to see they are valid for the user who is signing in and if so, the user’s API session will be marked as trusted.
- Use MFAStatus to determine the user's API Trusted Session status. Knowing the Trusted Session status allows developers to know whether they should perform the MFA process before attempting to use an MFA protected endpoint. In addition to returning the Trusted Session status, if MFAStatus returns a success, the user's API session will also be marked as trusted.
- If the user's API session is not trusted, you'll need to use MFAChallenge to text a token to the user’s registered mobile phone. If no mobile phone is registered for the user, an error will be returned. MFAChallenge returns a
challengeIdthat will be used to authenticate the challenge.
- Next use MFAAuthenticate to validate a
tokenpreviously sent to the user’s mobile phone by MFAChallenge. If the challenge is successfullly validated, the user’s session will be marked as trusted.
- Use MFA protected endpoints