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

# Partner API Reference

> Endpoints, scopes, and error responses for the Hyperwisor Partner Platform.

Base URL:

```
https://hyperwisor.nikolaindustry.workers.dev/functions/v1
```

## Endpoints

| Method     | Path                               | Auth                       | Purpose                              |
| ---------- | ---------------------------------- | -------------------------- | ------------------------------------ |
| `GET/POST` | `/partner-oauth-authorize`         | — (browser)                | Login + consent; issues an auth code |
| `POST`     | `/partner-oauth-token`             | client\_id + secret / PKCE | Exchange code, or refresh            |
| `POST`     | `/partner-products`                | Bearer token               | Create / update a product            |
| `GET`      | `/partner-products?external_ref=…` | Bearer token               | Read product status                  |

## Scopes

| Scope                   | Grants                                                      |
| ----------------------- | ----------------------------------------------------------- |
| `manufacturer:products` | Create / read / update the manufacturer's products          |
| `manufacturer:devices`  | Read device counts / status for the manufacturer's products |
| `manufacturer:firmware` | Fetch firmware / flashing config for a product              |
| `manufacturer:profile`  | Read basic manufacturer profile                             |

Request only the scopes you need. Every scope must be in your client's allowed set.

## Token lifetimes

| Token              | Lifetime                          |
| ------------------ | --------------------------------- |
| Authorization code | 5 minutes, single use             |
| Access token       | 1 hour                            |
| Refresh token      | 60 days (rotated on each refresh) |

## Errors

OAuth endpoints return standard OAuth 2.0 error codes:

| Code                     | Meaning                                                        |
| ------------------------ | -------------------------------------------------------------- |
| `invalid_client`         | Unknown client, or bad `client_secret` / PKCE                  |
| `invalid_grant`          | Bad/expired/used code, redirect mismatch, or bad refresh token |
| `invalid_scope`          | A requested scope isn't allowed for your client                |
| `unsupported_grant_type` | `grant_type` not supported                                     |

Partner API errors are JSON `{ "error": "…" }` with an HTTP status:

| Status | Meaning                                               |
| ------ | ----------------------------------------------------- |
| `401`  | Missing / invalid / expired token                     |
| `403`  | `insufficient_scope` — token lacks the required scope |
| `400`  | Missing or invalid parameters                         |
| `404`  | Resource not found                                    |

## Security notes

<Warning>
  Keep your `client_secret` on a server you control — never ship it in a browser or
  mobile bundle. For browser/mobile clients, register a **public** client and use PKCE.
</Warning>

* Redirect URIs are an **exact allowlist** per client — no wildcards.
* Codes and tokens are stored hashed; tokens can be revoked.
* Always send and verify the OAuth `state` parameter.