> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hive.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server.

# Authentication & Authorization

Hive uses the **OAuth 2.0 Authorization Code Flow with PKCE** to issue access tokens. This flow is required for every integration.

> **Note**
>
> The Client Credentials Flow is not supported. Only the Authorization Code Flow with PKCE is
> supported.

## Required headers

Every API request needs both headers:

```
Authorization: Bearer <access_token>
X-Partner-Id: <client_id>
```

| Header          | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `Authorization` | OAuth 2.0 Bearer token                                         |
| `X-Partner-Id`  | Your OAuth application client ID (scoped to your organization) |

`X-Partner-Id` is validated by the API gateway. Requests with a missing or invalid value are rejected before they reach the API, so if a request fails this way, check the header.

> **Info**
>
> Access tokens are **scoped to a single brand**. All data read or written through the API is
> automatically associated with the brand that authorized the token, so you don't provide a brand
> identifier in requests.

## What you need

During onboarding, Hive provides:

* Your **OAuth client ID** (also used as the `X-Partner-Id` header)
* Your **OAuth client secret**
* The **authorization endpoint**
* The **token endpoint**

You provide Hive with one or more **callback (redirect) URLs** where users are sent after authorizing your app. You can manage these in the [Partner Portal](/docs/partner-portal). Only registered callback URLs are accepted.

## OAuth endpoints

Hive's OAuth implementation uses two domains:

* `app.hive.co`: user authorization (the user signs in to Hive)
* `api.hive.co`: token management and API access

| Step           | Method and endpoint                            |
| -------------- | ---------------------------------------------- |
| Authorization  | `GET https://app.hive.co/oauth/api/authorize/` |
| Token exchange | `POST https://api.hive.co/oauth/token/`        |
| Token refresh  | `POST https://api.hive.co/oauth/token/`        |
| Token revoke   | `POST https://api.hive.co/oauth/revoke_token/` |

## Authorization flow

#### Redirect the user to Hive

Send the user to the authorization endpoint with your `client_id`, requested scopes, and a
PKCE `code_challenge`.

#### The user approves access

The user selects a brand they administer and approves access. Hive then redirects the user
to your callback URL with an authorization `code`.

#### Exchange the code

Your backend exchanges the authorization code at the token endpoint.

#### Store the tokens

Hive returns `access_token`, `refresh_token`, `expires_in`, `token_type`, and `scope`. Store
them securely.

### Authorization request

```
https://app.hive.co/oauth/api/authorize/
  ?response_type=code
  &client_id=partner_abc123
  &redirect_uri=https://example.com/oauth/callback
  &scope=events:write%20orders:write%20contacts:write%20segments:write
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
```

| Parameter               | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| `response_type`         | Must be `code`                                                                |
| `client_id`             | Your OAuth client ID provided by Hive                                         |
| `redirect_uri`          | One of your registered callback URLs                                          |
| `scope`                 | Space-separated list of requested scopes                                      |
| `code_challenge`        | PKCE challenge generated by your application                                  |
| `code_challenge_method` | Must be `S256`                                                                |
| `state`                 | Optional. Returned unchanged on the redirect. Recommended for CSRF protection |
| `tour_id`               | Optional. Preselects the brand to authorize                                   |

After the user grants access, Hive redirects to your callback URL with an authorization code:

```
https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=af0ifjsldkj
```

Verify that `state` matches the value you sent before exchanging the code.

### Brand selection

On the consent screen, the user picks a brand they administer. Each token is scoped to that one brand; to connect multiple brands, run one authorization per brand.

If you pass `tour_id`, that brand is preselected. An invalid `tour_id` returns `400 Bad Request`; a brand the user doesn't administer returns `403 Forbidden`.

If the user has already authorized your app with the same scopes and still has an unexpired access token, the consent screen is skipped and Hive redirects immediately, reusing the previously authorized brand.

### Token response

```json
{
    "access_token": "...",
    "refresh_token": "...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "events:read events:write ..."
}
```

## Scopes

Scopes define the permissions your application requests. You **must** include scopes in the authorization request, or the issued access token won't have permission to access the API.

| Scope            | Description                        |
| ---------------- | ---------------------------------- |
| `orders:read`    | Read access to orders              |
| `orders:write`   | Create or update orders            |
| `events:read`    | Read access to events              |
| `events:write`   | Create or update events            |
| `contacts:read`  | Read access to contacts            |
| `contacts:write` | Create or update contacts          |
| `segments:read`  | Read access to segments            |
| `segments:write` | Create or update segments          |
| `campaigns:read` | Read access to campaigns and stats |

Pass scopes as a **space-separated list** in the `scope` parameter. We strongly recommend requesting all of them, so the user authorizes read and write access to every available resource:

```
scope=events:read events:write orders:read orders:write contacts:read contacts:write segments:read segments:write campaigns:read
```

## Token lifecycle

* **Access tokens** are valid for **1 hour** (3600 seconds). Refresh proactively using the `expires_in` value rather than waiting for a `401`.
* **Refresh tokens rotate on every use.** Each refresh returns a new access token **and** a new refresh token, which you must store. The previous refresh token keeps working for 2 minutes after rotation (returning the same new tokens), so a refresh whose response was lost can be safely retried.
* **Refresh tokens expire after 90 days of inactivity.** Because each refresh issues a new refresh token, an integration that refreshes at least once every 90 days stays connected indefinitely. If your integration is seasonal or low-traffic, refresh on a schedule (we recommend at least monthly).
* An expired access token does **not** invalidate your refresh token. You can refresh at any time afterward.
* **Re-authorization** (running the full OAuth flow again) is only required if your refresh token is lost, expired, or invalidated, for example if you fail to store the new refresh token returned by a refresh.

Store these values from every token response:

* `access_token`
* `refresh_token`
* `expires_in`: token lifetime in seconds

## Revoking tokens

Revoke a token with `POST https://api.hive.co/oauth/revoke_token/`. The request requires client authentication: send `token`, `client_id`, and `client_secret` as form fields.

## Implementation examples

Hive's [public GitHub repo](https://github.com/HiveHQ/hive-oauth-example) contains simple reference implementations of the authorization code flow in [JavaScript (Node)](https://github.com/HiveHQ/hive-oauth-example/tree/master/examples/node) and [Python](https://github.com/HiveHQ/hive-oauth-example/tree/master/examples/python).

> **Tip**
>
> You can point your preferred AI coding assistant at the repository to help you implement the
> authorization code flow in your own platform.

## Important notes

* PKCE is required for all integrations.
* The Client Credentials Flow is not supported.
* Store tokens securely on your backend. Never expose `access_token`, `refresh_token`, or `client_secret` client-side.
* After the 2-minute grace period, a used refresh token is rejected.
* Callback URLs must be registered with Hive in advance. Unregistered URLs are rejected.
* API requests with expired or invalid access tokens return `401 Unauthorized`.
* A valid token missing a required scope returns `403 Forbidden`. A token not issued through this OAuth flow returns `403` with `Token is not authorized for API v2.`
* If the authorized brand hasn't been set up for your integration, requests return `404 Not Found`. Contact Hive to resolve it.
* Refreshing with an expired or invalid refresh token returns `400 Bad Request` with `"error": "invalid_grant"`.