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 when it is inactive or idle for 48 hours, and provides limited access to the BILL API.
MFA operations are not available with token-based sign in
You do not have access to any MFA operation with token-based sign in. All BILL MFA operations require you to sign in with
/v2/Login.json.
Generate 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 Sync & Integrations > Tokens.
- Click NEW to create a new sync token.
- Set up a NAME and click SAVE. This name is your
userNamefor signing in with/v2/Login.json.
A new token is generated. This token is your password for signing in with /v2/Login.json.
Sign in with a token
In this cURL example, you sign in to your API sandbox developer account with /v2/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 /v2/ListOrgs.json. |
devKey | Your developer key is used to identify your developer account in your API requests. See Sandbox API sign up for information about generating a developer key. |
curl --request POST \
--url 'https://api-stage.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 available. This sessionId expires when it is inactive or idle for 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. | - |
| MFA | - | You do not have permissions for any MFA operation. |
| 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. | You do not have permissions for creating customer bank accounts or 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 CRUD operations. | You do not have permissions for 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 can search for vendor and customer organizations in the BILL network. In addition, you can invite vendors and customers in the BILL network. | You cannot send an invitation to a vendor that is not in the BILL network. You cannot cancel existing network connection and invitations. |
Updated 9 days ago