Token-based sign in
IMPORTANT
This section is about the token-based sign in process for working with the BILL v3 API. See Authentication with Spend & Expense API token for information about getting a BILL Spend & Expense API token.
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 in your BILL account.
- Click Apps > Tokens.
- Click NEW to create a new sync token.
- Set up a NAME and click SAVE. This name is your
userNamefor signing in with/v3/Login.json.
A new token is generated. This token is your password for signing in with /v3/Login.json.
Signing in with a token
In this cURL example, you sign in to your API sandbox developer account with /v3/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://gateway.stage.bill.com/connect/v3/login' \
--header 'accept: application/json' \
--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. | - |
Updated 3 months ago