Authentication & Authorization | Hive API

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

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.

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

{
    "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 contains simple reference implementations of the authorization code flow in JavaScript (Node) and Python.

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