canonical: https://jentic.com/apis/bill.com/bill-authentication # BILL Authentication API Jentic publishes the only available OpenAPI specification for BILL Authentication API, keeping it validated and agent-ready. The Authentication API is the entry point to BILL's v2 platform - callers exchange a developer key, organization ID, username, and password for a session ID via /Login.json, then carry that session ID on every subsequent call to the Approvals, Customer Management, Vendor, and other BILL APIs. The surface also covers MFA challenge, MFA authenticate, MFA status, session inspection, and logout. It is small but mandatory. ## For AI agents Log in to BILL, satisfy MFA challenges, and obtain a session ID required by every other BILL v2 API endpoint. ## Scope Does not handle accounts payable, AR, or vendor management directly - use only for BILL session login, MFA, and session inspection. ## Capabilities - Authenticate with developer key, org ID, username, and password via /Login.json to obtain a session ID - Trigger an MFA challenge for the current session through /MFAChallenge.json - Submit an MFA token to complete authentication via /MFAAuthenticate.json - Check MFA status with /MFAStatus.json before issuing privileged calls - Inspect the active session details using /GetSessionInfo.json - Log out and invalidate the session with /Logout.json ## Use cases ### Session Bootstrap for BILL Integrations Every BILL v2 integration starts with a successful /Login.json call that returns a session ID. The session ID is then attached to every Approvals, AR, AP, and Vendor call until /Logout.json invalidates it. Integrations typically wrap login behind a reauth helper that detects expired sessions and re-issues credentials before retrying the failed downstream call. Example prompt: Call POST /Login.json with devKey, orgId, userName, and password, capture the sessionId from the response, and use it for subsequent BILL calls ### MFA Step-Up for Sensitive Operations BILL accounts with MFA enabled must complete the challenge before privileged actions like Approve.json or payment runs are allowed. /MFAChallenge.json triggers delivery of the MFA token, /MFAAuthenticate.json verifies it, and /MFAStatus.json confirms the session is now MFA-authenticated. Integrations gate sensitive workflows behind a successful /MFAStatus.json check. Example prompt: Call /MFAChallenge.json, prompt the user for the token, call /MFAAuthenticate.json, and verify with /MFAStatus.json before running an approval ### Session Inspection and Cleanup Long-running BILL integrations track active sessions for audit and clean shutdown. /GetSessionInfo.json returns the user, organization, and session metadata for diagnostics; /Logout.json terminates the session cleanly when a job ends. Both prevent dangling sessions from accumulating on the BILL side and keep audit logs tight. Example prompt: Call /GetSessionInfo.json to log session metadata, then /Logout.json at job end ### Agent-Driven BILL Login via Jentic An AI agent acting on a BILL workflow first searches Jentic for a login intent, loads the BILL /Login.json operation, and executes it with the user's credential bundle from the vault. The returned session ID stays inside Jentic's runtime and is automatically attached to subsequent BILL calls, so the agent itself never sees the devKey, password, or session ID. This makes downstream Approvals or Customer-Management actions safe to chain. Example prompt: Search Jentic for 'log in to BILL', load /Login.json, execute with the vault credentials, and proceed with downstream BILL operations using the returned sessionId ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /Login.json | Authenticate and obtain a session ID | | POST | /Logout.json | Invalidate the active session | | POST | /MFAChallenge.json | Trigger an MFA challenge | | POST | /MFAAuthenticate.json | Submit an MFA token to complete authentication | | POST | /MFAStatus.json | Check whether MFA has been completed | | POST | /GetSessionInfo.json | Inspect the active session | ## Key resources - **Login and Logout** — Establish and tear down BILL v2 sessions - **MFA** — Trigger MFA challenges, authenticate tokens, and check MFA state - **Session Info** — Inspect the active session's user and organization metadata ## Why Jentic - **Setup:** Wiring the BILL Authentication API by hand means posting your developer key, organization id, and user password to /Login.json, then carrying MFA state across follow-up calls yourself. Through Jentic you install once, import BILL Authentication from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** The Authentication API carries its identifiers in the request body of RPC-style operations rather than the URL path, so limit the agent to the operations it needs, such as logging in or checking session info. You choose that set, so MFA challenge or logout are not reachable unless you include them. - **Credential handling:** Your BILL developer key, organization id, and user password are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'log in to BILL' or 'complete an MFA challenge', and Jentic returns the matching Authentication operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **BILL Approvals API** — AP approval workflow that requires the session ID from this Authentication API - **BILL Customer Management API** — AR customer records that also depend on a BILL session - **BILL Connect Events API** — Webhook subscriptions for BILL platform events ## FAQ ### Why is there no official OpenAPI spec for BILL Authentication API? BILL documents its v2 API in narrative form on developer.bill.com but does not publish the underlying OpenAPI document. Jentic generates and maintains a structured OpenAPI specification so AI agents and developers can call BILL Authentication API via tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the BILL Authentication API itself require? The /Login.json endpoint accepts a developer key, organization ID, user name, and password as form-encoded fields. It returns a session ID that all other BILL v2 endpoints require. Through Jentic, the developer key, username, and password are stored encrypted in the vault and never enter the agent's context. ### How do I handle BILL accounts with MFA enabled? After /Login.json succeeds, call /MFAChallenge.json to trigger token delivery, /MFAAuthenticate.json to submit the user's token, then /MFAStatus.json to confirm the session is fully authenticated. Privileged operations (Approve, payment execution) require MFA to be complete on the session. ### How long is a BILL session ID valid for? BILL platform sessions expire after a period of inactivity defined by the org's security configuration - for unattended integrations the safest pattern is to catch the auth-error response on a downstream call and re-run /Login.json before retrying. /GetSessionInfo.json reveals current session details for diagnostics. ### How do I log in to BILL through Jentic? Run `pip install jentic`, then `await client.search('log in to BILL')`, `await client.load(...)` for /Login.json, and `await client.execute(...)`. Jentic uses the credentials in the vault and retains the returned sessionId for subsequent BILL operation calls within the same execution context. ### Should I call /Logout.json at the end of a job? Yes for short-lived scripts and integrations - /Logout.json releases the session on the BILL side, preventing dangling sessions and keeping audit logs clean. Long-running services typically reuse a session with reauth-on-401 logic instead of logging out and back in for each call. ### Can I limit what my agent is allowed to do with the BILL Authentication API? Yes. Because your Jentic One instance is self-hosted, your own rules decide which BILL Authentication operations and credentials the agent may use. Since these are RPC-style operations that carry their identifiers in the request body rather than the URL path, you scope access by choosing the exact operation set the agent gets, such as /Login.json and /GetSessionInfo.json only. Operations you leave out, like /MFAChallenge.json or /Logout.json, are simply not reachable by the agent.