# Create an auth session
Source: https://www.desktopaccountingapi.com/docs/api/reference/operations/authsessionscreate/

`POST https://api.desktopaccountingapi.com/v1/auth-sessions`

Operation ID: `authSessions.create`. Tag: Auth sessions.

Creates a time-limited link to the hosted setup flow, where the end user connects their QuickBooks Desktop company file through the QuickBooks Web Connector. Create a new auth session each time you show the link; each one expires after `linkExpiryMins`.

Authentication: `Authorization: Bearer <secret key>`.

## Headers

- `Idempotency-Key` (string): Makes a write safe to retry. Repeating a key with the same request attaches to or replays the original instead of creating a second one. 1–255 printable ASCII characters, retained 7 days. Reusing a key with a different request returns `422 IDEMPOTENCY_KEY_REUSED`. 1–255 characters; example `6f1c2a0e-1f7e-4c55-9a7a-0b2d2c9e3a10`.

## Request body (application/json, required)

- `publishableKey` (string, required): The project's publishable key. It must belong to the same project as the secret key. example `pk_test_4eC39HqLyjWDarjtT1zdp7dc`.
- `endUserId` (string, required): The end user who will connect QuickBooks Desktop. example `eu_01j9x4m6v4c8k2t7q0r5s3w1zb`.
- `linkExpiryMins` (integer): Minutes until `authFlowUrl` expires, 15–10080 (7 days). Default 30. 15 to 10080; default `30`; example `30`.
- `redirectUrl` (string (uri)): Absolute `https` URL to return the end user to when they finish (`?authSessionId=...&status=completed`) or stop (`status=canceled`). Test projects may also use `http://localhost`. max 2000 characters; example `https://app.example.com/quickbooks/connected`.

Minimal example:

```json
{
  "publishableKey": "pk_test_4eC39HqLyjWDarjtT1zdp7dc",
  "endUserId": "eu_01j9x4m6v4c8k2t7q0r5s3w1zb"
}
```

## Responses

### 201

The created auth session.

Body (application/json): object (AuthSession).

- `id` (string, required): Unique identifier for the auth session. example `authsess_01j9x4m6v4c8k2t7q0r5s3w1ze`.
- `objectType` (string, required): Always `auth_session`. one of `auth_session`.
- `createdAt` (string (date-time), required): When the auth session was created. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
- `endUserId` (string, required): Unique identifier for the end user. example `eu_01j9x4m6v4c8k2t7q0r5s3w1zb`.
- `clientSecret` (string, required): Secret that authorizes the setup flow. It is part of `authFlowUrl`; treat both as credentials and send them only to the end user. example `authsess_secret_7fYk2m9QxR3pL8vN1cT6bW4zH0dJ5sA9gE2uK7iO3qM`.
- `authFlowUrl` (string (uri), required): Link to the hosted setup flow. Open it on the computer that runs QuickBooks Desktop, share it with the end user, or embed it in an iframe. example `https://connect.desktopaccountingapi.com/setup/authsess_secret_7fYk2m9QxR3pL8vN1cT6bW4zH0dJ5sA9gE2uK7iO3qM`.
- `expiresAt` (string (date-time), required): When `authFlowUrl` stops working. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
- `redirectUrl` (string, nullable, required): Where the end user returns after the flow, or `null`.

### Errors

Every error body is the error object described at https://www.desktopaccountingapi.com/docs/errors/.

- `400`: The request is invalid. Codes: `UNKNOWN_HEADER`, `INVALID_JSON`, `INVALID_PARAMETER`, `UNKNOWN_PARAMETER`, `IDEMPOTENCY_KEY_INVALID`.
- `401`: The API key is missing or invalid. Codes: `API_KEY_MISSING`, `API_KEY_INVALID`, `PUBLISHABLE_KEY_INVALID`.
- `403`: The operation is not permitted. Codes: `API_KEY_READ_ONLY`, `PUBLISHABLE_KEY_PROJECT_MISMATCH`, `TEST_COMPANY_FILE_LIMIT_REACHED`.
- `404`: The object does not exist in this project. Codes: `RESOURCE_MISSING`.
- `422`: The request is well formed but cannot be processed. Codes: `IDEMPOTENCY_KEY_REUSED`.
- `429`: Too many requests. Codes: `RATE_LIMITED`.
- `500`: Unexpected server error. Codes: `INTERNAL_ERROR`.
- `503`: QuickBooks Desktop or the service is not available. Codes: `SERVICE_UNAVAILABLE`.