@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 }>

listIdentityUsers(brandOrgId, options?)

List identity users — the sign-in records behind profiles. Identity users are always organization-scoped, so brandOrgId is required.

const page = await admin.listIdentityUsers('org_abc123', { search: 'teach', limit: 50 });
Copy

Returns: Promise<PaginatedResponse<IdentityUser>>

getIdentityUser(userId, brandOrgId)

Get one identity user by its own ID (not the profile ID).

Returns: Promise<IdentityUser>

findIdentityUserByEmail(email, brandOrgId)

The identity user that signs in with an address — its canonical email or one of its aliases. Exact and case-insensitive, one request; null when no account in the organization uses the address. (Not listIdentityUsers({ search }), whose substring search covers only the email and name.)

const user = await admin.findIdentityUserByEmail('online@school.com', 'org_abc123');
Copy

Returns: Promise<IdentityUser | null>

addIdentityUserAlias(userId, email, brandOrgId)

Add a sign-in alias. The account's email never changes; the alias signs in to the same account from the moment it is added — the caller attests that the person owns it.

const user = await admin.addIdentityUserAlias('user_123', 'online@school.com', 'org_abc123');
console.log(user.loginEmails); // ['teach@school.com', 'online@school.com']
Copy

Throws AdminApiError with status 409 when the address is the account's own email, already one of its aliases, or in use by another account in the organization.

Returns: Promise<IdentityUser>

removeIdentityUserAlias(userId, email, brandOrgId)

Remove a sign-in alias. If it was the contact address, mail returns to the account's email. The account's email itself cannot be removed (status 409). An address that is not one of the account's aliases is status 404 — the same as an unknown user, so look the account up first if you need to tell the two apart.

Every alias or contact change also mails a plain notice to the account's email and to the address that received mail before the change, so the account holder learns of it.

Returns: Promise<IdentityUser>

setIdentityUserContactEmail(userId, email, brandOrgId)

Choose where the account's mail goes: its email or one of its verified aliases (status 400 otherwise). Security codes, password resets and verification mail follow it.

await admin.setIdentityUserContactEmail('user_123', 'online@school.com', 'org_abc123');
Copy

Returns: Promise<IdentityUser>

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

IdentityUser

The sign-in record behind a profile. One per (email, organization).

IdentityUserAlias

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