> ## 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.

# Connect with Hyperwisor (OAuth)

> Standard OAuth 2.0 authorization-code flow — send your user to log in, receive an access token to call the Partner API on their behalf.

Connecting uses the OAuth 2.0 **authorization-code** grant. Confidential clients
authenticate with a `client_secret`; public clients (SPAs / mobile) use **PKCE**.

## 1. Send the user to authorize

Redirect the user's browser to the authorize endpoint:

```
GET /partner-oauth-authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
  &scope=manufacturer:products
  &response_type=code
  &state=RANDOM_STRING
  # PKCE (public clients):
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
```

Hyperwisor shows a login + consent screen. On approval, the user is redirected
back to your `redirect_uri` with a one-time code:

```
YOUR_REGISTERED_REDIRECT_URI?code=AUTH_CODE&state=RANDOM_STRING
```

<Warning>
  The `redirect_uri` must **exactly** match one registered for your `client_id`,
  and every requested scope must be in your allowed set — otherwise the request is
  rejected. Always verify `state` matches what you sent.
</Warning>

## 2. Exchange the code for a token

Your backend exchanges the code (JSON or form-encoded):

```bash theme={null}
curl -X POST https://hyperwisor.nikolaindustry.workers.dev/functions/v1/partner-oauth-token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE",
    "redirect_uri": "YOUR_REGISTERED_REDIRECT_URI",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
```

For **public clients**, omit `client_secret` and send `code_verifier` instead:

```json theme={null}
{ "grant_type": "authorization_code", "code": "AUTH_CODE", "redirect_uri": "…",
  "client_id": "…", "code_verifier": "THE_ORIGINAL_VERIFIER" }
```

**Response:**

```json theme={null}
{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "manufacturer:products"
}
```

The code is single-use and expires in **5 minutes**. Store the tokens against the
partner user (never in a browser for confidential clients).

## 3. Call the Partner API

Send the access token as a Bearer header:

```
Authorization: Bearer ACCESS_TOKEN
```

See [Create Products](/partners/create-product).

## Refreshing

Access tokens live **1 hour**. Refresh (rotates both tokens):

```bash theme={null}
curl -X POST https://hyperwisor.nikolaindustry.workers.dev/functions/v1/partner-oauth-token \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "refresh_token", "refresh_token": "…",
        "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" }'
```

<Note>
  The first time a user approves a `manufacturer:*` scope, their Hyperwisor account
  is provisioned as a **manufacturer**. Existing accounts are upgraded, not duplicated.
</Note>