Token-based sign in

When you sign in to your BILL developer account with user credentials (userName, password, orgId, and devKey), the generated sessionId enables you to call any BILL API endpoint without restrictions. This sessionId expires when it is inactive or idle for 35 minutes and you are automatically signed out.

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.

Generating a token

You can generate a token with the BILL sandbox web app.

  1. Sign in to the BILL sandbox web app. Use the email address and password you created as part of the sign-up process.
  2. Click SETTINGS at the top-right of your BILL account.
  3. Click Tokens under Apps.
  4. Click NEW to create a new sync token.
  5. Set up a NAME and click SAVE. This name is your userName for signing in with /v2/Login.json.

A new token is generated. This token is your password for signing in with /v2/Login.json.

Signing in with a token

In this cURL example, you sign in to your API sandbox developer account with /Login.json. The required fields are userName, password, orgId, and devKey.

Sign-in credentialsDescription
userNameYour username is the name that you set up for creating your token.
passwordYour password is the generated token.
orgIdYour organization ID. You can retrieve this value with /ListOrgs.json.
devKeyYour developer key (sent to you when you create a developer account).
curl --request POST \
--url 'https://api-sandbox.bill.com/api/v2/Login.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'userName={token_name}' \
--data 'password={token_value}' \
--data 'orgId={organization_id}' \
--data 'devKey={developer_key}'

In the response, the generated sessionId is generated. This sessionId does not expire.

Token-based sign in permissions

When you sign in with a token, you have access to specific BILL API services.

BILL objectAccess availableAccess not available
OrganizationWhen you list organizations with /ListOrgs.json, you get only the orgId of the organization account you use for generating the token.-
Managing documentsYou can upload documents to BILL and retrieve documents attached to a BILL object.-
UserYou have permissions for retrieving users.

In addition, you can view user role profiles and their permissions.
You do not have permissions for creating, updating, or deleting users.
CustomerYou have permissions for all customer CRUD operations. This includes customer bank account operations and setting customer authorization.-
InvoiceYou have permissions for all invoice, recurring invoice, and credit memo CRUD operations.

In addition, you can record an AR payment for an invoice.
You do not have permissions for sending an invoice or mailing an invoice.
AR transactions dataYou have permission for retrieving information about invoice credits, received payments, convenience fees, and AR summary.-
VendorYou have permissions for all vendor and vendor bank account CRUD operations.-
BillYou have permissions for all bill, recurring bill, and vendor credit CRUD operations.

In addition, you can record an AP payment for a bill.
You do not have permissions for paying, canceling, or voiding a vendor bill payment.
AP transactions dataYou have permissions for retrieving information about bill credits, sent payments, bill payments, payment disbursement, check images, and AP summary.-
Approval policyYou have permissions for all approval policy CRUD operations.

In addition, you can retrieve information about approval policy approvers, vendor credit approvers, and bill approvers.
You do not have permissions for approving or denying the approval of a bill or vendor credit.

You do not have permissions for creating, updating, or deleting approval policy approvers.

You do not have permissions for setting bill approvers.
Accounts trackingYou have permissions for all accounts tracking CRUD operations.-
Network operationsYou have permissions for all network operations.-