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:
- If a user has already created an MFA Trusted Session that is trusted, include
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 again 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
- Use MFAStatus to determine the status of a user's API Session. The Trusted Session status allows developers to know whether they should perform the MFA process again 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.