> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airstore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> client.oauth — OAuth session management for interactive connections

```typescript theme={null}
const session = await airstore.oauth.createSession({
  integrationType: 'gmail',
  workspaceId: 'ws_abc123',
})
// Redirect user to session.authorize_url
```

The OAuth resource handles interactive connection flows where users authorize access in their browser. Create a session, redirect the user, then poll for completion.

***

## createSession()

Create an OAuth session and get the authorization URL.

```typescript theme={null}
const session = await airstore.oauth.createSession({
  integrationType: 'gmail',
  workspaceId: 'ws_abc123',
  returnTo: 'https://app.example.com/settings',
})

console.log(session.authorize_url)
// "https://accounts.google.com/o/oauth2/v2/auth?..."
```

Redirect the user to `authorize_url` in their browser. After they approve, Airstore handles the callback.

**Parameters**

| Parameter         | Type              | Required | Description                                                                                                                   |
| ----------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `integrationType` | `IntegrationType` | Yes      | Provider: `gmail`, `gdrive`, `github`, `notion`, `linear`, `slack`                                                            |
| `workspaceId`     | `string`          | No       | Workspace to attach the connection to. Required for org/admin tokens; optional for workspace tokens (derived from the token). |
| `returnTo`        | `string`          | No       | URL to redirect to after OAuth completes (same-tab flow). If omitted, a static success/error page is shown.                   |

**Returns** `Promise<OAuthSession>`

| Field           | Type     | Description                 |
| --------------- | -------- | --------------------------- |
| `session_id`    | `string` | Session ID for polling      |
| `authorize_url` | `string` | URL to redirect the user to |

***

## getSession()

Check the current status of an OAuth session.

```typescript theme={null}
const status = await airstore.oauth.getSession('sess_abc123')

console.log(status.status) // "pending" | "complete" | "error"
```

**Parameters**

| Parameter   | Type     | Required | Description                     |
| ----------- | -------- | -------- | ------------------------------- |
| `sessionId` | `string` | Yes      | Session ID from `createSession` |

**Returns** `Promise<OAuthSessionStatus>`

| Field           | Type                  | Description                           |
| --------------- | --------------------- | ------------------------------------- |
| `status`        | `string`              | `pending`, `complete`, or `error`     |
| `error`         | `string \| undefined` | Error message if status is `error`    |
| `connection_id` | `string \| undefined` | Connection ID if status is `complete` |

***

## poll()

Poll a session until it completes, errors, or times out. This is a convenience wrapper around `getSession()` that checks at a regular interval.

```typescript theme={null}
const result = await airstore.oauth.poll('sess_abc123')
console.log(result.connection_id) // "conn_xyz789"
```

With custom options:

```typescript theme={null}
const result = await airstore.oauth.poll('sess_abc123', {
  timeout: 120_000,  // 2 minutes
  interval: 1_000,   // check every second
})
```

**Parameters**

| Parameter   | Type     | Required | Default  | Description                        |
| ----------- | -------- | -------- | -------- | ---------------------------------- |
| `sessionId` | `string` | Yes      | --       | Session ID from `createSession`    |
| `timeout`   | `number` | No       | `300000` | Max time to wait in ms (5 minutes) |
| `interval`  | `number` | No       | `2000`   | Polling interval in ms             |

**Returns** `Promise<OAuthSessionStatus>` -- resolves with `status: "complete"`.

**Throws**

* `AirstoreError` if the session status is `error` (user denied, provider error, etc.)
* `AirstoreError` if the timeout is reached before the session completes