@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

Roles cannot be changed via updateProfile. Any roles field passed in is silently stripped from the request body to prevent accidental privilege escalation (e.g. forwarding an untrusted client request body). Use addRole / removeRole instead.

Returns: Promise<UserProfile>

addRole(profileId, role, brandOrgId?)

Add a role to a user profile. Idempotent — if the role is already present, the profile is returned unchanged.

const updated = await admin.addRole('profile_123', 'public-files', 'org_abc123');
console.log(updated.roles); // ['private-files', 'public-files']
Copy

Returns: Promise<UserProfile>

removeRole(profileId, role, brandOrgId?)

Remove a role from a user profile. Idempotent — if the role is not present, the profile is returned unchanged. Other roles are preserved.

const updated = await admin.removeRole('profile_123', 'public-files', 'org_abc123');
Copy

Returns: Promise<UserProfile>

Concurrency note. addRole / removeRole are implemented as read-modify-write and are not atomic. Concurrent calls on the same profile can race — serialize role mutations per profile in your own code.

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