PubNub Keyset Management

When to Use This Skill

• Creating a new PubNub project (app + keyset)
• Separating dev / staging / production keysets
• Rotating publish, subscribe, or secret keys
• Asking about demo keys vs your own keys
• Configuring a custom origin / vanity domain
• Auditing existing keyset hygiene before a launch
• Using the

  manage_apps

  or

  manage_keysets

  MCP tools

Core Workflow

1. Map environments to keysets: one keyset per environment (dev / staging / prod). Never share.
2. Identify the three key types: publish (client-safe), subscribe (client-safe), secret (server-only).
3. Lock keys out of source control: secrets manager or env vars only.
4. Plan rotation: schedule and document rotation cadence and owner.
5. Decide on custom origin: only for paid plans, only when branding or routing demands it.
6. Avoid demo keys: for anything that isn't a copy-paste sample on the PubNub website.

Reference Guide

• references/keysets-and-environments.md — apps, keysets, the three key types, dev/staging/prod separation
• references/key-rotation-and-hygiene.md — rotation cadence, secrets management, source-control rules
• references/demo-keys.md — when demo keys are acceptable and when they are dangerous
• references/custom-origin.md — custom CNAME / vanity domain setup with PubNub Support

Key Implementation Requirements

App vs Keyset Hierarchy

Environment Separation

• Use distinct keysets per environment: dev, staging, production.
• Never share a keyset across environments. A test message in dev must never reach a production subscriber.
• Different environments may enable different add-ons (e.g., shorter TTLs, debug logging, looser rate limits in dev).

Key Types and Where Each Belongs

pub-c-...

sub-c-...

sec-c-...

Server-Side Initialization Skeleton

const PubNub = require('pubnub');
const pubnub = new PubNub({
  publishKey: process.env.PN_PUBLISH_KEY,
  subscribeKey: process.env.PN_SUBSCRIBE_KEY,
  secretKey: process.env.PN_SECRET_KEY,
  userId: 'server-instance-' + os.hostname()
});

Client-Side Initialization Skeleton

Constraints

• Never expose the secret key in client-side code. It belongs only on servers and only in environments that mint Access Manager tokens.
• Never commit any key to source control. Use a secrets manager (AWS Secrets Manager, Vault, Doppler, etc.) or per-environment env vars.
• One keyset per environment. Mixing dev and prod data through a shared keyset is the most common preventable incident.
• Demo keys are public. Never use them outside copy-paste sample code on the PubNub website.
• Custom origin requires PubNub Support coordination. It is not self-service and is paid-plan only.
• Rotating the secret key requires coordinated grant re-issuance. Plan a maintenance window or use overlapping grants.

MCP Tools

user-pubnub

• manage_apps

  — list, create, inspect, and update apps in the Admin Portal

• manage_keysets

  — list, create, inspect, and update keysets; toggle add-ons (Presence, Persistence, Access Manager, Stream Controller, etc.)

See Also

• pubnub-security — for secret-key handling, Access Manager, encryption (AES-256), TLS, DDoS, IP allowlist, SOC 2 / HIPAA compliance reports
• pubnub-app-developer — for

  new PubNub(...)

  client SDK initialization patterns and userId requirements
• pubnub-observability — for tracking keyset usage metrics and per-key billing
• pubnub-scale — for Stream Controller add-on configuration on a keyset
• pubnub-choose-docs-path — for routing other PubNub questions

Output Format

1. Always state which environment the keys are for (dev/staging/prod).
2. Show env-var or secrets-manager retrieval, never inline literals.
3. Explicitly call out that the secret key must not appear in the client snippet.
4. Note which add-ons need to be enabled in the Admin Portal for the snippet to work.
5. If asked about keys for a sample, default to recommending the user create their own free keyset rather than using demo keys.