> For the complete documentation index, see [llms.txt](https://docs.spiroq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spiroq.com/en/operator-api/operator-api/pripojeni.md).

# Connection and API key

## Base URL

```
https://vending-admin-hub-worker.aschermann.workers.dev/v1
```

Send requests **from your ERP / WMS server**. The token **does not belong** in a browser, a mobile app, or in logs.

***

## Creating a key

1. Sign in to the [Admin Hub](https://app.spiroq.com).
2. Open **Settings**.
3. In the menu, choose **Operator API**.
4. Fill in **Key name** (for example `WMS production`, at most 80 characters). An empty name is stored as `API key`.
5. Click **Create key**.
6. The token is shown **once** and copied to the clipboard. Store it securely in secrets on your server. You will not read it from the hub again.

In the list you see only the token **prefix** (the start of the string), the creation date, and the last use.

The tab is available on the **Enterprise** tier. Without it, the Admin Hub does not offer the tab.

### Revoking

On the key, click **Revoke**. The next request with this token returns `401`. A new key has a different token — replace it in the integration, and only then revoke the old one.

***

## What the token looks like

```
spk_live_…
```

Example shape (do not use it as a real key):

```
spk_live_a1b2c3d40123456789abcdef01234567
```

***

## Headers

```http
Authorization: Bearer spk_live_…
Content-Type: application/json
Idempotency-Key: <required on POST / PUT / PATCH, 1–200 characters>
```

Do not send the `Idempotency-Key` header on `GET`. On a write (`POST`, `PUT`, and `PATCH` requests) it is required — see [Jobs and idempotency](/en/operator-api/operator-api/joby.md).

***

## Identifiers in the URL (`:ref`)

Instead of a UUID you can use a natural key **within your account**. To avoid conflicts, we still recommend a unique UUID:

| Source   | `:ref`                                    |
| -------- | ----------------------------------------- |
| Machine  | UUID **or** serial number                 |
| Product  | UUID **or** exact SKU **or** exact EAN    |
| Category | UUID **or** exact name (case-insensitive) |

When an SKU, EAN, or category name matches more than one record, the API returns `409 conflict`.

```
GET /v1/machines/a1b2c3d4e5f6
GET /v1/machines/11111111-1111-1111-1111-111111111111
```

***

## Step 1 — first request

```bash
export SPIROQ_API="https://vending-admin-hub-worker.aschermann.workers.dev/v1"
export SPIROQ_TOKEN="spk_live_…"

curl -sS -D - "$SPIROQ_API/machines" \
  -H "Authorization: Bearer $SPIROQ_TOKEN"
```

Success:

```json
{
  "machines": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "serialNumber": "a1b2c3d4e5f6",
      "name": "Lobby machine",
      "status": "online",
      "tier": "enterprise"
    }
  ]
}
```

| HTTP | `code`                  | Typical cause                                                                      |
| ---- | ----------------------- | ---------------------------------------------------------------------------------- |
| 401  | `unauthorized`          | missing Bearer, wrong or revoked token                                             |
| 403  | `feature_not_available` | the account does not have the Enterprise tier                                      |
| 429  | `rate_limited`          | limit exceeded, see [Authentication](/en/operator-api/operator-api/autentizace.md) |

***

## Handling the token

* A token with full rights can read and change **all** machines and products on your account.
* One key per integrated system. If it leaks, revoke the key and issue a new one.
* Send it only in the `Authorization` header, **never in the query string or in the request body**.
* Calls belong on the ERP / WMS **backend**, not in a browser frontend.