Partner authentication

Authenticate partner API calls, manage RSA public keys, sign playback JWTs, and pass validated authorization into the Hive HTML5 plugin.

PARTNER STATE Partner token

Required for service endpoints that create or manage partner-specific resources.

SHARED ACCESS Share token

Grants access to selected resources through a shareable URI.

PLAYBACK Signed JWT

Authorizes a customer, event, and approved manifest for plugin playback.

Choose the correct token

Partner tokens are assigned manually by Hive operations and authenticate the partner making a service API request. Supply one as partner_token or X-Hive-Partner-Token. Share tokens are generated for selected resources and are supplied as share_token. Missing or invalid authentication returns 403 Forbidden; successful authentication does not guarantee authorization to the requested resource.

Partner header

curl https://api.hivestreaming.com/v1/publickey/9001 \
  -H "X-Hive-Partner-Token: <partner-token>"

Partner query

curl "https://api.hivestreaming.com/v1/publickey/9001?partner_token=<partner-token>"

Share token

curl "https://api.hivestreaming.com/v1/stats/metrics/<partner-id>/<customer-id>?share_token=<share-token>"

Follow the playback authorization flow

Hive validates a signed JWT containing partner, customer, event, and video details against a public key you previously published.

1 Generate Create a 3072-bit RSA key pair

2 Publish Store the public key with Hive

3 Sign Create the JWT with the private key

4 Initialize Pass JWT details to initSession

5 Validate Hive checks key, claims, and manifest

6 Play Load the resolved session manifest

Run Hive’s JWT reference implementation

View repository ↗

Hive’s public jwt-auth-examples project packages every required authentication step as a runnable Node.js script. It requires Node.js 18 or later, plus the partner ID and partner API token supplied by Hive.

Setup

git clone https://github.com/hivestreaming/jwt-auth-examples.git
cd jwt-auth-examples
npm install
cp .env.example .env

Generate key

npm run generate-rsa-key

# OpenSSL alternative
npm run generate-rsa-key:openssl

Publish key

npm run public-key-post

Create JWT

npm run create-jwt:manifest

# Or authorize streams with regex patterns
npm run create-jwt:regex

Manage keys

npm run public-key-get
npm run public-key-get-all
npm run public-key-delete

HIVE_API_ENV

prod or test.

HIVE_PARTNER_TOKEN

Partner API token supplied by Hive.

HIVE_PARTNER_ID

Partner ID supplied by Hive.

HIVE_CUSTOMER_ID

Existing Hive customer entity.

HIVE_PARTNER_KEY_ID

Unique ID for the RSA public key.

VIDEO_ID

Unique event/video ID on your platform.

EVENT_NAME

Name displayed in the Hive Portal.

MANIFESTS

Comma-separated URLs without query parameters.

MANIFEST_REGEXES

Patterns grouping a manifest’s playlists and segments.

QUALITY_REGEXES

Patterns identifying equivalent qualities.

JWT_EXPIRY

Expiration in Unix seconds.

PRIVATE_KEY_PATH

Path to the private PEM file.

What the scripts do: Node’s crypto module creates a 3072-bit RSA pair and exports the public modulus and exponent as JWK values. jsonwebtoken signs the configured payload with RS256 and the configured keyId.

Keep it server-side: the project reads the partner token and private key from the environment and filesystem. Never move these values into browser code or commit a populated .env or private key.

Generate and publish the RSA key

Use an RSA key with a 3072-bit modulus. The public-key keyId must be non-empty and contain only alphanumeric characters, hyphens, or underscores. Keep the private key on your trusted backend and publish only its public counterpart.

Generate key

openssl genpkey -algorithm RSA \
  -out ./private-key.pem \
  -pkeyopt rsa_keygen_bits:3072

Publish key

curl -X POST https://api.hivestreaming.com/v1/publickey \
  -H "X-Hive-Partner-Token: <partner-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerId": "9001",
    "keyId": "production-key-01",
    "exponent": "AQAB",
    "modulus": "<base64url-modulus>",
    "expiration": 1767225600
  }'

Rotation: create a new key, begin signing JWTs with its kid, retain the previous key until outstanding tokens expire, then delete it.

Manage keys through the Public Key API

PRODUCTION https://api.hivestreaming.com/v1

TEST https://api-test.hivestreaming.com/v1

Authentication: every operation accepts either partner_token or X-Hive-Partner-Token.

Browser limitation: this API does not return Access-Control-Allow-Origin. Swagger’s browser-based “Try it out” will not work; use the generated curl command or call it from a backend.

Responses: 403 indicates missing authorization. Retrieve may also return 404 for a missing key or 410 for a deleted key. Create may return 400 for invalid content, expiration, modulus/exponent, key ID, or a duplicate database record.

Schema note: the current Swagger marks createdAt as required in PublicKeyStorePayload, but does not define that property in the payload schema or the published example. Confirm expected create behavior with Hive support.

Build the header and claims

Sign the JWT using the private key whose public counterpart is in Hive key storage. The header identifies the RSA algorithm and published key. The payload identifies the partner, customer, event, approved media, and expiration.

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id"
}

Manifest payload

{
  "iss": "partner://9001",
  "sub": "event-id",
  "ver": "1.0",
  "aud": "https://hivestreaming.com",
  "cid": "15",
  "evn": "Event name",
  "man": ["https://stream.example.com/live/manifest.m3u8"],
  "exp": 1767225600
}

Regex payload

{
  "iss": "partner://9001",
  "sub": "event-id",
  "ver": "1.0",
  "aud": "https://hivestreaming.com",
  "cid": "15",
  "evn": "Event name",
  "man": [],
  "reg_manifest": ["stream\\.example\\.com/live/manifest\\.m3u8"],
  "reg_quality": ["stream\\.example\\.com/live/.*\\.(m3u8|ts)"],
  "exp": 1767225600
}

Regex authorization: reg_manifest and reg_quality require Core Plugin 11.1.0 or later, and man must be empty. Earlier versions use the legacy reg claim. Work with the Hive Partner team to finalize stream-specific expressions.

Initialize the Hive session

initSession accepts a string Hive Ticket for backwards compatibility or a token object. Hive cross-checks manifest against the JWT’s approved media and videoId against its sub claim.

const token = {
  jwt: signedJwt,
  manifest: "https://stream.example.com/live/manifest.m3u8",
  videoId: "event-id",
  endpoint: "prod", // "test" or "prod"; prod is the default
};

try {
  const session = await plugin.initSession(token);
  player.load(session.manifest);
} catch ({ errCode, errStr }) {
  cdnFallback();
}

Handle authorization failures

The initSession Promise rejects with errCode and errStr when authorization cannot be validated.

01

The public key identified by kid was not found.

02

videoId does not match the JWT sub claim.

03

The JWT customer ID does not exist in Hive.

04

The requested manifest is not allowed by man or regex claims.

05

The JWT has expired.

06

The public JWK has expired or was deleted.