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 Sign up process for more information.

Authentication overview

Authentication overview

Sign in credentialsDescription
UsernameYour username is the email address used to sign in to your BILL sandbox developer account.
PasswordYour password is used to sign in to your BILL sandbox developer account.
Organization IDYour BILL sandbox developer account represents your organization in BILL. The organization ID is a unique alphanumeric value that begins with 008.
Developer keyYour 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 sessionId only when the session is inactive or idle for 35 minutes. See API login 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.

APIDescription
/Login.jsonSign in to your BILL sandbox developer account.

See Login for more information.
/GetSessionInfo.jsonRetrieve the currently signed in user and organization.

See Retrieve API session details for more information.
/Logout.jsonSign 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.

  1. Sign in to generate a sessionId value with /Login.
  2. Generate an MFA challenge ID with /MFAChallenge.json. When you call /MFAChallenge.json, a token is sent to your mobile device registered with BILL.
  3. Validate the challenge ID and token with /MFAAuthenticate. At this point, the sessionId (from step one) is MFA trusted.

MFA operations

The MFA operations API includes MFAChallenge, MFAAuthenticate, and MFAStatus.

APIDescription
/MFAChallenge.jsonGenerate 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.jsonAuthenticate 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.jsonRetrieve 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.