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

# HotspotSystem plugin

> HotspotSystem hotspot management data - locations, customers, subscribers, vouchers and the sessions each one produced.

Use **HotspotSystem** through Corsair: one client, typed API calls.

HotspotSystem runs Wi-Fi hotspots and reports who connected, how, and what they paid. This plugin wraps the v2 REST API.

Generate an API key in the Control Center under Tools & Settings > API Keys, then store it as the account's `api_key`. It is sent in the `sn-apikey` header. The docs also describe HTTP Basic with the key as the username and an empty password, which the plugin does not use, so the key never travels in the URL.

Things to know before you call:

* **Every operation is a read.** The documented API has 18 GET operations and no write, so nothing here changes state on the provider's side and every call is safe to retry.
* **The account-wide reads and the per-location reads are different operations, not a filter.** `customers.list` covers every location the key can see; `locations.customers` covers one. Both exist for customers, subscribers, vouchers and each of the four transaction types.
* **Paging uses `limit` and `offset`, and the next offset is in a response header.** Each list returns `next_offset` when the API's `Link` header names a next page, and omits it on the last page. Pass it back as `offset` to continue. The API cannot return the header and the body together through the shared client, so the paged reads use their own request that returns both.
* **`fields` and `sort` name properties of the response object.** `fields` narrows the response to a comma separated list, which the plugin takes as an array. `sort` takes one property name, with a leading `-` for descending. A name the resource does not have is refused by the API rather than ignored.
* **Dates are `2013-05-21 17:53:39` strings.** The notes page documents that format, and the transaction records use an ISO timestamp instead. Neither is converted, so both are `string` in the output.
* **A location ID can be a string or a number.** The Swagger types it as a string, while every transaction record returns `location_id` as a number, so the per-location operations accept either.
* **Some transaction fields are documented only as `TODO`.** The Swagger leaves every `MacTransaction`, `PaidTransaction`, `SocialTransaction` and `VoucherTransaction` field undocumented, so nothing on them is required and the values are passed through exactly as sent, including `smscountry`.
* **No pagination on `locations.options`.** It returns every location as `{ id, name }` with no `metadata` and no paging.
* **No inbound webhooks yet.** HotspotSystem can POST `customer.create`, `subscriber.create` and `transaction.*.create` events to a callback URL set up in the Control Center, signed with an HMAC-SHA256 header. This plugin does not register a webhook route for them, so new records are read with the list operations.

**What you get:**

* 18 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/hotspotsystem better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/hotspotsystem better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/hotspotsystem better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/hotspotsystem better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { hotspotsystem } from '@corsair-dev/hotspotsystem';

export const corsair = createCorsair({
	plugins: [
		hotspotsystem(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the HotspotSystem API key before the first call: `pnpm corsair setup --plugin=hotspotsystem --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> hotspotsystem()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'hotspotsystem',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List the first ten locations with just their ID and name**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.hotspotsystem.api.locations.list({
	fields: ['id', 'name'],
	limit: 10,
});
```

**Read the account customers**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.hotspotsystem.api.customers.list({ limit: 25 });
```

See the full list on the [API](https://docs.corsair.dev/plugins/hotspotsystem/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/hotspotsystem/api.md)
>
> Every `hotspotsystem.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.