Get started with BILL OAuth

This guide explains how to create BILL OAuth credentials, generate an access token, and make your first authenticated API request across multiple BILL product lines.

OAuth client credentials are the recommended authentication method across Accounts Payable (AP), Accounts Receivable (AR), and Spend & Expense. They replace the username, password, and developer key (devKey) for AP and AR, and the standalone API token (apiToken) for Spend & Expense.

See the Create an access token API to learn how to generate an access token.

Before you begin

• You must have an admin role in at least one active BILL product (AP, AR, or Spend & Expense).
• OAuth client credentials must be enabled for your organization.

Sign up and sign in to the sandbox environment (Optional)

If you are testing your integration before working in production, create a sandbox organization. If you already have an active organization, proceed to Create a developer app.

1. Go to the BILL BILL sandbox sign-up page.
2. Enter your name, email address, contact information, and company details.
   Note: Use a real phone number you can access. BILL requires this number for sandbox setup and multi-factor authentication (MFA) setup.
3. Select both BILL AP & AR and Spend & Expense to provision both products in one sandbox organization.
4. Select None for accounting software, and then select Get Started.
5. Verify your email and complete the MFA setup.
6. Go to the BILL sandbox sign-in page, and then sign in with your credentials.
7. Enter your company information using test data. The Website URL field is optional. Submit the form to continue.
8. Complete at least one onboarding tutorial and skip the bank account step. A credit application is not required in the sandbox environment.

The BILL dashboard opens with your AP & AR and Spend & Expense organizations created. BILL automatically adds test data, which includes:

• Demo transactions
• Budgets
• Cards, including a few test cards

Create a developer app

1. In the upper-right corner of the BILL web app, select your Profile icon > Connected apps.

2. Select Create app.

3. Select the access scope, and then select the terms of service check box.

   • Full access to my BILL org(s): Complete access, including payment creation and funding account updates.
     Note: This scope requires MFA with the real phone number you entered during BILL sign-up.
   • Accounting data access: Accounting data only. Excludes payment creation and funding account updates.

   To learn which API operations each scope allows, see OAuth API scope capabilities.

4. Select Create app. The app is created, and the client ID and client secret are generated.

5. Copy your client ID and client secret, and store them securely. You need both values to generate an access token.

   Note: Your client secret appears only once. You cannot retrieve it after closing this window.

6. Select Done.

Generate an access token

Use the client ID and client secret with the token endpoint (POST /authx/token) to generate a short-lived access token.

Before you begin

Fork the BILL v3 API Postman collection and set up your environment. See BILL v3 API on Postman for more information.

Token generation URLs

Each environment has its own token generation URL.

Note: Use sandbox credentials with the sandbox endpoint and production credentials with the production endpoint. Credentials do not work across environments. See Sandbox vs Production for information about the API sandbox and production environments.

Sample request

In this example, you generate an access token using POST /authx/token.

curl --request POST \
--url 'https://auth.stage.bill.com/authx/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}'

Response

A 200 OK response returns your access_token. The token expires after 3600 seconds (1 hour).

{
    "access_token": "eyJhbG_123...",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Make your first API request

It is time to start building!

Pass your access_token as a Bearer token in the Authorization header of any BILL v3 API request.

You do not need to send a devKey, sessionId, or apiToken with your requests. The access_token is all you need to authenticate.

Sample request

In this example, you retrieve a list of bills in the sandbox environment.

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/bills' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access_token}'

Response

A 200 OK response returns a list of bills.

 { "results": [
        {
            "id": "00n02DEFVQGJLUDdxup8",
            "recordStatus": "ACTIVE",
            "archived": false,
            "vendorId": "00902JLDTTXQAZM2n8f4",
            "vendorName": "Happy Music Supplies",
            "amount": 200.00,
            "paidAmount": 200.00,
            "dueAmount": 0.00,
            "scheduledAmount": 0.00,
            "creditAmount": 0.00,
            "dueDate": "2025-10-30",
            "invoice": {
                "invoiceNumber": "202501",
                "invoiceDate": "2025-09-30"
            },
            "billLineItems": [
                {
                    "id": "bli02AKWMRSPIJBhltmm",
                    "amount": 110.00,
                    "description": "headphone"
                },
                {
                    "id": "bli02DLPPJIQFSOhltmn",
                    "amount": 90.00,
                    "description": "charger"
                }
            ],
            "paymentStatus": "PAID",
            "approvalStatus": "UNASSIGNED",
            "createdBy": "00602GCKPMZWVGCZp3u9",
            "createdTime": "2025-07-30T18:46:43.000+00:00",
            "updatedTime": "2025-09-24T18:00:21.000+00:00"
        },
        {
            "id": "00n02GPMKBOIAFAdxulc",
            "recordStatus": "ACTIVE",
            "archived": false,
            "vendorId": "00902SBXIPMPTPQ2n8dk",
            "vendorName": "Happy Music Supplies",
            "amount": 200.00,
            "paidAmount": 200.00,
            "dueAmount": 0.00,
            "scheduledAmount": 0.00,
            "creditAmount": 0.00,
            "dueDate": "2025-10-30",
            "invoice": {
                "invoiceNumber": "202501",
                "invoiceDate": "2025-09-30"
            },
            "billLineItems": [
                {
                    "id": "bli02CSELABEFXEhltif",
                    "amount": 120.00,
                    "description": "headphone"
                },
                {
                    "id": "bli02GRIVALVYEWhltig",
                    "amount": 80.00,
                    "description": "charger"
                }
            ],
            "paymentStatus": "PAID",
            "approvalStatus": "UNASSIGNED",
            "createdBy": "00602GCKPMZWVGCZp3u9",
            "createdTime": "2025-07-30T16:00:32.000+00:00",
            "updatedTime": "2025-09-24T18:00:20.000+00:00"
        }
            ]
  }