billcom v1.0.0

The pack names a reference, never a secret. Installing a pack registers capabilities and makes them governable; registration is not connectivity. The credential is created at the provider and held in the client's own secret manager under the reference the pack names, and deployment testing is still required to show the credential path works and cannot be bypassed.

Reference

secret-ref-billcom-v3-session

Custody

customer_vault

Injection

header (sessionId)

A BILL v3 API session id, held in the client's own secret manager. The stored material must be the complete sessionId header value — the session id itself, with no scheme prefix. An external token process mints it: POST https://gateway.prod.bill.com/connect/v3/login with username, password, organizationId and devKey — where username/password are either user credentials or an AP & AR sync token name/value generated in the BILL web app (Settings > Sync & Integrations > Tokens) — and stores only the returned sessionId; the sign-in credentials (user password or sync token value) are themselves secret material and stay with that external process. The devKey has a different lifecycle: BILL documents devKey and sessionId as required headers on EVERY API call, not just login, so the devKey must also reach the trusted HTTP executor — it does not stay with the external sign-in process. The deployment must resolve the devKey from its own secret manager as a second secret reference (separate from this pack's sessionId reference), inject it into the devKey header on every call alongside the injected sessionId, and give it protections equivalent to the session id's: held in executor memory only for the lifetime of a call, never written to logs, traces or diagnostics, and never present in crash dumps. That second-secret wiring is outside this pack's single injection point and is a pre-enablement review item — if the executor cannot supply the devKey header, this pack is not enableable as wired. Expiry and revocation: BILL documents that a session minted from user credentials expires after 35 minutes idle, and a session minted from a sync token after 48 hours idle, so the external process must re-login on expiry — the executor must not attempt renewal itself; signing out with POST /v3/logout terminates the session, and an expired value fails closed; revoking a sync token in the BILL web app prevents that token minting NEW sessions — preventing issuance is a different event from invalidating sessions already minted, and BILL's documentation does not describe credential or sync-token changes as ending sessions already in flight before their documented idle expiry. Least privilege: a sync-token session has no payment operations, no approve/deny and no MFA-protected operations, and is the right shape for the reads and bill creation; the approve capability needs a user-credential session, which BILL documents as unrestricted within the user's permissions — choose the underlying BILL user's role accordingly. MFA note: payment creation requires an MFA-trusted session, which this pack never uses because it does not register payment creation. Executor hygiene: the session id must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must never appear in crash reports; the executor's memory, log and crash handling are otherwise the deployment's review.

• billcom-vendors (api, pii): https://gateway.prod.bill.com/connect/v3/vendors
• billcom-bills (api, financial): https://gateway.prod.bill.com/connect/v3/bills
• billcom-payments (api, financial): https://gateway.prod.bill.com/connect/v3/payments
• billcom-bill-approvals (api, financial): https://gateway.prod.bill.com/connect/v3/bill-approvals/actions

Use a BILL API session whose underlying sign-in credentials carry only the access these capabilities need; the pack does not create one. The BILL v3 API authenticates every call with TWO headers, sessionId and devKey: this pack's credential reference stores the sessionId material for injection into the sessionId header, and the deployment must present the devKey header alongside every call — review how the deployment's HTTP executor supplies that second header before enabling, because if it cannot, this pack is not enableable as wired. The production host is gateway.prod.bill.com (path prefix /connect); gateway.stage.bill.com is the sandbox and is not registered. Bill creation is registered as pay at the R3 floor, not create at R2: POST /v3/bills itself creates a bill object and schedules no payment — payment is the separate, MFA-gated POST /v3/payments endpoint this pack deliberately does not register — but BILL documents vendor auto-pay (when autoPay is enabled for a vendor, BILL automatically pays the vendor when a bill is created for that vendor), so under a documented account configuration the call initiates a payment workflow whose documented end state is a processed payment; pay is one of the IRREVERSIBLE ACTIONS (delete, send, pay, deploy, approve, share and transfer). Approving a bill is registered as approve at the R3 floor — BILL documents that approved bills can be paid — and approve is likewise irreversible; both irreversible actions require a person, and the registered cost ceiling on bill creation plus a policy budget are the second control. All reads are collection reads only: single-record reads (GET /v3/vendors/{vendorId}, GET /v3/bills/{billId}, GET /v3/payments/{paymentId}) exist in the API and are deliberately not registered. Documented exclusions, framed as what this pack does not register: payment creation (POST /v3/payments, POST /v3/payments/bulk and POST /v3/payments/mass — money moves, and BILL requires an MFA-trusted session), recording offline AP payments, cancelling or voiding payments, vendor creation/update/archive and all vendor bank account operations, recurring bills (including recurring-bill autoPayment), bill update/replace/archive/restore, bill approval policy management, the entire AR surface, the Spend & Expense API surface (which uses a different, token-based authentication), documents and attachments upload, webhook subscription management, MFA operations, and the v2 API. An AP & AR sync token sign-in is the least-privilege credential shape for the reads and for bill creation (sync-token sessions have no payment and no approve/deny access); the approve capability requires a user-credential session, so a deployment that enables the approve capability must accept the broader session. AAES has not been certified by Bill.com; the endpoints here are a reviewable default, not a vendor guarantee.

Draft review record dated 2026-09-21 · Reviewer: aaes-eng (an opaque id that resolves internally to the responsible reviewer)

• https://developer.bill.com/llms.txt (retrieved 2026-09-21)
• https://developer.bill.com/reference/login.md (retrieved 2026-09-21)
• https://developer.bill.com/docs/bill-keys-tokens.md (retrieved 2026-09-21)
• https://developer.bill.com/docs/token-based-sign-in.md (retrieved 2026-09-21)
• https://developer.bill.com/reference/listvendors.md (retrieved 2026-09-21)
• https://developer.bill.com/reference/listbills.md (retrieved 2026-09-21)
• https://developer.bill.com/reference/listpayments.md (retrieved 2026-09-21)
• https://developer.bill.com/reference/createbill.md (retrieved 2026-09-21)
• https://developer.bill.com/reference/billapprovedenyactions.md (retrieved 2026-09-21)
• https://developer.bill.com/docs/ap-bill-approvals.md (retrieved 2026-09-21)
• https://developer.bill.com/docs/ap-bills.md (retrieved 2026-09-21)
• https://developer.bill.com/docs/vendor-payment-options.md (retrieved 2026-09-21)
• https://developer.bill.com/docs/ap-payments.md (retrieved 2026-09-21)

A pack review is not a vendor or examiner attestation. A retrieval date says when a source page was read; it does not by itself establish what the page said then. No pack is vendor-endorsed, and none has been connectivity-tested against a live vendor tenant.