Authentication
An organization User must sign in with their BILL credentials for access to resources in the organization.
Login overview
Sign in to your BILL sandbox developer account with /Login.json. The required fields for signing in are userName, password, orgId, and devKey.
IMPORTANT
Retrieve the required fields for signing in as part of your sandbox sign up process. See API sign up process for more information.
Authentication overview
| Sign in credentials | Description |
|---|---|
| Username | Your username is the email address used to sign in to your BILL sandbox developer account. |
| Password | Your password is used to sign in to your BILL sandbox developer account. |
| Organization ID | Your BILL sandbox developer account represents your organization in BILL. The organization ID is a unique alphanumeric value that begins with 008. |
| Developer key | Your developer key is used to uniquely identify your developer account in your API requests. |
In response, an API session is created and a sessionId is generated. Use the sessionId in all subsequent operations to confirm that you are in a signed in session.
If the API session is inactive or idle for 35 minutes, the session expires and you are automatically logged out.
IMPORTANT
After signing in for the first time, any subsequent API operation resets the 35 minutes timer. You are required to sign in again and generate a new
sessionIdonly when the session is inactive or idle for 35 minutes. See API sign in best practices for more information.You can also sign in to your BILL developer account with a user-generated token. The generated sessionId does not expire, and provides limited access to the BILL API. See Token-based sign in for more information.
Login operations
The login API includes Login, GetSessionInfo, and Logout.
| API | Description |
|---|---|
/Login.json | Sign in to your BILL sandbox developer account. See Login for more information. |
/GetSessionInfo.json | Retrieve the currently signed in user and organization. See Retrieve API session details for more information. |
/Logout.json | Sign out of your BILL sandbox developer account. See Logout for more information. |
Multi-Factor Authentication (MFA)
A set of protected API operations require Multi-Factor Authentication (MFA) for signing in with a trusted API session.
- Invite a vendor to setup ePayments with
/SendVendorInvite.json - Add a vendor bank account with
/VendorBankAccount.json - Pay a vendor using BILL with
/PayBills.json - Invite a customer to BILL with
/SendInvite.json
NOTE
See Multi-factor authentication (MFA)/2-step verification in the BILL Help Center for more information about all the security measures in place for your BILL account operations.
Signing in with an MFA trusted API session is a three-step process.
- Sign in to generate a
sessionIdvalue with/Login. - Generate an MFA challenge ID with
/MFAChallenge.json. When you call/MFAChallenge.json, a token is sent to your mobile device registered with BILL. - Validate the challenge ID and token with
/MFAAuthenticate. At this point, thesessionId(from step one) is MFA trusted.
MFA operations
The MFA operations API includes MFAChallenge, MFAAuthenticate, and MFAStatus.
| API | Description |
|---|---|
/MFAChallenge.json | Generate an MFA challenge ID and send a token to your mobile device registered with BILL. Using /MFAChallenge.json is step two of signing in with an MFA trusted API session.See Generate MFA challenge for more information. |
/MFAAuthenticate.json | Authenticate the challenge ID (generated with /MFAChallenge.json) and token that was sent to your mobile device registered with BILL. Using /MFAAuthenticate.json is step three of signing in with an MFA trusted API session.See Validate MFA challenge ID for more information. |
/MFAStatus.json | Retrieve the status of the current MFA session. If the MFA session expires, you must follow the three-step process again and sign in with an MFA trusted API session. See Retrieve MFA status for more information. |
Updated 3 months ago