@hiyve/admin

Server-only admin client for the Hiyve Cloud API. Manages user profiles, organizations, and API keys.

Warning: This package is for server-side (Node.js) use only. Secret keys must never be exposed to the browser. Three layers of enforcement prevent accidental client-side usage.

Installation

npm install @hiyve/admin
Copy

Quick Start

import { AdminClient } from '@hiyve/admin';

const admin = new AdminClient({
  secretKey: process.env.HIYVE_SECRET_KEY,
  environment: 'production',
});

// List profiles
const result = await admin.listProfiles('org_abc123', { limit: 20 });

// Get a single profile
const profile = await admin.getProfile('profile_123', 'org_abc123');

// Update a profile
const updated = await admin.updateProfile('profile_123', 'org_abc123', {
  name: 'John Smith',
  organization: 'Acme Corp',
});

// Deactivate a profile
await admin.deactivateProfile('profile_123', 'org_abc123');
Copy

Constructor

new AdminClient(config: AdminConfig)
Copy

API Reference

listProfiles(brandOrgId?, options?)

List user profiles for an organization. Returns a paginated response.

const result = await admin.listProfiles('org_abc123', {
  page: 1,
  limit: 20,
  search: 'john',
  metadata: { role: 'admin' },
});
console.log(result.data);   // UserProfile[]
console.log(result.total);  // total matching profiles
console.log(result.pages);  // total pages
Copy

Returns: Promise<PaginatedResponse<UserProfile>>

getProfile(profileId, brandOrgId)

Get a single user profile by ID.

const profile = await admin.getProfile('profile_123', 'org_abc123');
console.log(profile.name, profile.email);
Copy

Returns: Promise<UserProfile>

updateProfile(profileId, brandOrgId, updates)

Update a user profile's fields.

const updated = await admin.updateProfile('profile_123', 'org_abc123', {
  name: 'John Smith',
  organization: 'Acme Corp',
  metadata: { department: 'Engineering' },
});
Copy

Returns: Promise<UserProfile>

deactivateProfile(profileId, brandOrgId)

Deactivate (soft-delete) a user profile. The profile is not permanently deleted.

const result = await admin.deactivateProfile('profile_123', 'org_abc123');
console.log(result.message); // 'Profile deactivated'
Copy

Returns: Promise<{ message: string; profile: UserProfile }>

listAllowedOrigins(orgId)

List the CORS allowed origins for an organization.

const result = await admin.listAllowedOrigins('org_abc123');
console.log(result.origins); // ['https://myapp.com', 'https://staging.myapp.com']
Copy

Returns: Promise<AllowedOriginsResponse>

setAllowedOrigins(orgId, origins)

Replace all allowed origins for an organization.

await admin.setAllowedOrigins('org_abc123', [
  'https://myapp.com',
  'https://staging.myapp.com',
]);
Copy

Returns: Promise<AllowedOriginsResponse>

addAllowedOrigins(orgId, origins)

Add origin(s) to the allowed list without removing existing ones.

await admin.addAllowedOrigins('org_abc123', ['https://new-app.com']);
Copy

Returns: Promise<AllowedOriginsResponse>

removeAllowedOrigins(orgId, origins)

Remove specific origin(s) from the allowed list.

await admin.removeAllowedOrigins('org_abc123', ['https://old-app.com']);
Copy

Returns: Promise<AllowedOriginsResponse>

Types

UserProfile

AllowedOriginsResponse

HiyveAuthUser

Authenticated user attached to req.hiyveUser by createAuthMiddleware.

Other Exported Types

Exported Constants

Server Middleware

Express-compatible route handlers for room tokens, cloud tokens, join tokens, AI note generation, health checks, and identity proxy. Mount all routes with a single call or use individual handlers.

Quick Start

import express from 'express';
import { mountHiyveRoutes, loadHiyveConfig } from '@hiyve/admin';

const app = express();
app.use(express.json());

const apiRouter = express.Router();
mountHiyveRoutes(apiRouter, loadHiyveConfig());
app.use('/api', apiRouter);

app.listen(3000);
Copy

This registers the following routes on the router:

• POST /generate-room-token — Generate a room token for WebRTC
• POST /generate-cloud-token — Generate a cloud token for AI services
• POST /generate-note — Generate AI-powered meeting notes
• POST /create-join-token — Generate a server-side join token
• GET /health — Health check
• ALL /hiyve/identity/* — Proxy to Hiyve Cloud identity endpoints

loadHiyveConfig(env?): HiyveServerConfig

Load configuration from environment variables. Reads APIKEY, CLIENT_SECRET, SERVER_REGION, SERVER_REGION_URL, and ENVIRONMENT.

const config = loadHiyveConfig(); // reads from process.env
const config = loadHiyveConfig(customEnv); // or pass a custom env object
Copy

mountHiyveRoutes(router, config): router

Mount all Hiyve routes on an Express-compatible router. Returns the router for chaining.

createHiyveHandlers(config): HiyveHandlers

Create individual handlers without mounting them. Use this when you need custom routing.

const handlers = createHiyveHandlers(loadHiyveConfig());
app.post('/api/room-token', handlers.roomToken);
app.post('/api/cloud-token', handlers.cloudToken);
app.post('/api/note', handlers.generateNote);
app.post('/api/join-token', handlers.joinToken);
app.get('/api/health', handlers.health);
app.all('/api/hiyve/identity/*', handlers.identityProxy);
Copy

Individual Handler Factories

Note: joinToken and identityProxy handlers are available via createHiyveHandlers() or mountHiyveRoutes() but are not exported as individual factory functions.

HiyveServerConfig

HiyveHandlers

Authentication Middleware

Verify end-user access tokens against Hiyve Cloud. Attach this middleware to routes that require a logged-in user.

import express from 'express';
import { createAuthMiddleware, loadHiyveConfig } from '@hiyve/admin';

const app = express();
const config = loadHiyveConfig();

// Protect routes — verified user available as req.hiyveUser
app.get('/api/me', createAuthMiddleware(config), (req, res) => {
  res.json({ user: req.hiyveUser });
});

// Optional auth — req.hiyveUser is null if no token provided
app.get('/api/public', createAuthMiddleware(config, { optional: true }), (req, res) => {
  res.json({ user: req.hiyveUser });
});
Copy

createAuthMiddleware(config, options?)

The middleware extracts the Bearer token from the Authorization header, verifies it against Hiyve Cloud, and attaches the authenticated user to req.hiyveUser (see HiyveAuthUser type above).

Server-Only Enforcement

This package is restricted to server-side (Node.js) environments. If used in a browser context, it will throw an error at both build time and runtime.

Migration from @hiyve/cloud

If you were previously importing AdminClient from @hiyve/cloud:

- import { AdminClient } from '@hiyve/cloud';
+ import { AdminClient } from '@hiyve/admin';
Copy

All types (UserProfile, AdminConfig, etc.) are also exported from @hiyve/admin.

License

Proprietary - Hiyve SDK