# Core concepts
Source: https://www.desktopaccountingapi.com/docs/get-started/concepts/

> Organizations, projects, keys, end users, connections, connectors and requests, and how a call reaches QuickBooks Desktop.

QuickBooks Desktop runs on your customer's Windows computer, not in the cloud. Everything in this API follows from that fact: requests wait in a queue until the customer's computer picks them up, the computer can be off, and QuickBooks itself can be busy. These are the objects you work with.

```
Organization ── Project (test or production) ─┬─ Secret keys, publishable key
                                               ├─ Webhook endpoints
                                               └─ End users ── Connection ─┬─ Connectors (Web Connector installs)
                                                                           ├─ Requests
                                                                           └─ Company file
```

## Organization

Your company's account. It holds team members, roles and billing. Members are owners, admins or members. Owners manage billing and roles; owners and admins manage projects and keys; members work with end users, setup links and the request log.

## Project

An isolated environment inside the organization, for example "Development" and "Production". A project's environment is either `test` or `production` and is fixed when you create it.

- Test projects are free and use `sk_test_` and `pk_test_` keys. Use them with sample company files and trial installations of QuickBooks.
- Production projects use `sk_live_` and `pk_live_` keys and are billed per active company file. See [Billing and pricing](https://www.desktopaccountingapi.com/docs/platform/billing/).

A key only reaches end users in its own project. Two projects never share data.

## Secret key and publishable key

A secret key (`sk_test_...` or `sk_live_...`) authenticates every API call from your server. A project can have many named secret keys, so you can rotate them. The publishable key (`pk_...`) is a public project identifier that you pass when you create setup links. See [Authentication](https://www.desktopaccountingapi.com/docs/get-started/authentication/).

## End user

Your customer, as seen by the API. An end user has your own identifier (`sourceId`), a company name that the setup flow shows, and a contact email for your records. We never email end users.

Create one end user per QuickBooks company file. If a customer keeps two company files, create two end users.

## Connection

The link between an end user and one QuickBooks company file. It has a [status](https://www.desktopaccountingapi.com/docs/connect/connection-status/) (`pending_setup`, `online`, `offline`, `quickbooks_unavailable`, `company_file_mismatch`, `disabled`), the company name and QuickBooks version it last saw, and the queue of requests waiting for that file. The end user object returns it in `integrationConnections`.

## Connector

One installation of the QuickBooks Web Connector that serves a connection: one `.qwc` file, one Web Connector username and one password. A connection usually has one connector. When your customer moves to a new computer and runs setup again, the new computer gets a new connector and the old one is turned off once the new one works.

## Auth session and the setup flow

An auth session is a time-limited setup link (`authFlowUrl`) for one end user. The person at the QuickBooks computer opens it and follows five short steps: download the connector file, allow access in QuickBooks, enter the password in the Web Connector and wait for the live check. See [Connect an end user](https://www.desktopaccountingapi.com/docs/connect/setup-flow/).

## Request

Every call that needs QuickBooks, such as listing invoices, creating a customer, a health check or passthrough, becomes a request with an ID like `req_01j9...`. A request moves through statuses: `queued`, then `sent` to the Web Connector, then `succeeded` or `failed`. You can read any request back with `GET /v1/requests/{id}`, and the dashboard request log shows its timeline. See [Request lifecycle](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/).

Platform calls such as creating an end user also return a request ID for support, but they never queue.

## The QuickBooks Web Connector

Intuit's free Windows program that lets web services talk to QuickBooks Desktop. It polls our server over HTTPS. Our connector file tells it to check in every 10 seconds, and more often while there is work. When a request is waiting, the Web Connector opens a session with QuickBooks, passes the request in and sends QuickBooks' answer back. Nothing listens on your customer's network, and their firewall needs no inbound rules.

Because the Web Connector polls, the first request after a quiet period waits for the next check-in. Follow-up requests in the same session are fast. [Request lifecycle](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/) has the numbers.

## QuickBooks objects

QuickBooks records come in two families, and the API keeps that split:

- **Lists**: customers, vendors, items, accounts, classes, terms and similar. They have a `name` and `fullName`, can be hierarchical (`Parent:Child`), and are deactivated with `isActive: false` instead of deleted.
- **Transactions**: invoices, bills, checks, payments, journal entries and others. They have a `transactionDate`, often a `refNumber` and line items, and they can be deleted and, for most types, voided.

Every QuickBooks object has a QuickBooks-assigned `id` and a `revisionNumber` that changes on each edit. You need the current `revisionNumber` to update an object. See [Updates and line items](https://www.desktopaccountingapi.com/docs/quickbooks/updates-and-line-items/).