Create a project & API keys

What is a project?

A project is one product you measure. Examples: “Marketing website”, “SaaS app”, “Staging copy of SaaS”.

• Data from project A never appears in project B.
• Teammates are invited per project (Settings → People).
• Each project has its own API keys.

If you are brand new: create one project for the app you will install today. Add a second project later for staging if you want clean separation.

What is an API key?

An API key is a secret string. The SDK includes it with every request so HumanBehavior knows which project should store the data.

Security rules (non-negotiable)

1. Put keys in environment variables (.env.local, Vite env, etc.).
2. Never commit keys to git.
3. Client-side keys can still be extracted from the browser — treat them as “can send data into my project,” not as admin passwords.
4. If a key leaks, Rotate key or Delete key in Settings → Environments and create a new one.

Path A — First-time in-app onboarding

When you first create an account/project, HumanBehavior walks you through get-started routes.

Gate before Project Setup

New accounts hit Welcome & user profile (/get-started/user) first. After that, the top bar steps are:

1. Project Setup
2. Install
3. Verify
4. Billing

Top-bar actions (after user onboarding): Invite teammate, Need help? → Documentation (docs.humanbehavior.co), Watch video tutorial (YouTube). Book a call in that menu currently only closes the dropdown (no booking URL).

Step: Project Setup (/projects/:id/get-started/project)

Header: Project Setup — Set up your workspace details.

If your account email has a company domain, a checkbox appears:

Allow anyone with @{domain} email to join this project

the checkbox is shown and toggled in the UI, but Next only saves name and url — the domain-join flag is not sent with that save.

If you arrived via the CLI wizard with ?wizardCode=…, a notice appears: You’re setting up the CLI install flow…

Next / Saving… → loads an API key into session storage → /get-started/sdk (preserves wizardCode if present).

Step: Install (/get-started/sdk)

Header: Install — Set up takes less than 5 minutes. plus Confused? Watch a video tutorial (YouTube).

Connection status chip (top-right while on Install):

The page polls for SDK events (~1s). Next stays disabled until the SDK is connected. Skip Step is available only while not connected.

Install mode tabs

Three tabs under Instructions:

1. Install with AI

• Copyable wizard command (click field or copy control — tooltip Copy command / Copied):

  npx @humanbehavior/wizard@latest --dashboard-url {origin} --project {slug}

  (proj- prefix is stripped from the project id for --project.)

• Chip row: frameworks the AI installer can detect — React, Next, Vue, Angular, Svelte, Nuxt, Remix, Astro, Gatsby, HTML.

• Help note: To finish scanning, open your app and click around locally, or deploy it to start recording real users.

• Installation options menu:

  • Install manually — switches to Manual tab
  • Import existing data — switches to Import tab
  • Book a call — navigates to /demo

Also see the dedicated CLI wizard doc.

2. Install manually

Grid of framework cards. Clicking a card opens the Install manually modal with copy-paste steps for that stack.

Deep framework copy-paste detail: Manual install.

3. Import existing data

Panel: Import data from existing tools.

Tool chips:

PostHog fields (when PostHog is open)

Guided steps 1–5 in the UI, then:

Actions: Connect PostHog / Connecting... / Reconnect PostHog; link Open PostHog API keys; Back to the tool list.

Success: Connected to {name}. Imports will start shortly.

Skip Step reasons

Skip Step opens Skip setup? with:

When connected, Next advances to Verify (?step=verify).

Step: Verify (?step=verify)

Header: Verify — Confirm events are flowing from your product. Shows LIVE when connected.

Live event table + live replay preview. Primary CTA: Looks good (enabled when connected) → Billing (also marks billingReached).

Details: Verify data is flowing.

Step: Billing (/get-started/billing)

Full control map (cycles, $500 / $1000 / $2500 plans, annual gifts, Skip trial, payment modal): Billing.

Path B — You already have a project

1. Open the project.
2. Click Settings (gear) in the sidebar → opens the settings modal.
3. Open Environments (under Project).
4. If empty: No API keys yet. Create one below to start sending data.
5. Enter a name under New API key → Create key / Creating…
6. Per key: copy, overflow menu → View key / Hide key, Change name, Rotate key, Delete key
7. Footer: All API keys loaded

Environment variables to set in your app

Optional ingestion host override (local stacks):

Do not point ingestion at the dashboard origin unless you already proxy /api/ingestion/*.

Environments vs “environment” option in the SDK

• Settings → Environments / API keys: separate keys (often one for local, one for production).
• SDK options.environment: a string tag on events (e.g. production) used in Issues filters and release health.

Best practice: use a dev key for local work and a prod key for production deploys. Also set environment in init to match.

Empty / error states

Sidebar notes

Related

• Welcome & user profile
• Install with the wizard
• Manual install
• Billing
• Settings: Environments
• Settings: Billing