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 expires in 48 hours, and provides limited access to the BILL API.

Generating a token

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

Sign in to the BILL sandbox web app. Use the email address and password you created as part of the sign-up process.
Click SETTINGS at the top-right of your BILL account.
Click Tokens under Apps.
Click NEW to create a new sync token.
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 credentials	Description
`userName`	Your username is the name that you set up for creating your token.
`password`	Your password is the generated token.
`orgId`	Your organization ID. You can retrieve this value with `/ListOrgs.json`.
`devKey`	Your 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 expires in 48 hours.

Token-based sign in permissions

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

BILL object	Access available	Access not available
Organization	When you list organizations with `/ListOrgs.json`, you get only the `orgId` of the organization account you use for generating the token.	-
Managing documents	You can upload documents to BILL and retrieve documents attached to a BILL object.	-
User	You 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.
Customer	You have permissions for all customer CRUD operations. This includes customer bank account operations and setting customer authorization.	-
Invoice	You 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 data	You have permission for retrieving information about invoice credits, received payments, convenience fees, and AR summary.	-
Vendor	You have permissions for all vendor and vendor bank account CRUD operations.	-
Bill	You 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 data	You have permissions for retrieving information about bill credits, sent payments, bill payments, payment disbursement, check images, and AP summary.	-
Approval policy	You 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 tracking	You have permissions for all accounts tracking CRUD operations.	-
Network operations	You have permissions for all network operations.	-