BILL package v1.0.0

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.

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 minimum R3 tier, 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 designated actions requiring human approval.

Approving a bill is registered as approve at the minimum R3 tier — 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.

Excluded operations: 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 configuration to review and test; the vendor has not endorsed it.