API Keys 101 — How Vectreal Keys Actually Work, and How to Ship Them Safely

Before You Begin#

Vectreal API keys are managed in your dashboard at vectreal.com/dashboard/api-keys. You need to be an admin or owner of the organization to create or revoke keys — members and viewers can use embeds that depend on a key, but they cannot mint new ones.

If you have not connected an organization yet, the Vectreal Publisher walkthrough covers project setup. For framework integration after this post, see React Viewer Integration.

The Two-Minute Version#

If you only have two minutes:

1. Vectreal API keys are organization-scoped. There are no per-user "personal" keys today.
2. Each key is scoped to a subset of projects at creation. It cannot reach scenes outside that subset.
3. Keys are presented as vctrl_… Bearer tokens. The plaintext is shown exactly once at creation; only the last four characters are kept on file as a preview.
4. Keys carry an expiration of 30, 60, 90 days, or never. We strongly recommend setting one.
5. Domain allowlists at the project level are the second security layer — even a leaked key cannot be used from an un-allowed origin.

If that map is enough, jump to Three rotation patterns that match real deployments.

What an API Key Is, in One Diagram#

A Vectreal API key is not a single shared secret that unlocks the whole platform. Three layers stack on top of each other:

The first two layers live on the key itself. The third layer lives on the project. A request only succeeds when all three line up — same org, allowed project, allowed origin. That intersection is what makes a leaked key recoverable.

Creating a Key — Step by Step#

From the dashboard:

1. Open API keys → click Create API Key.
2. Name — keep it descriptive (Production Marketing Site, Staging Pipeline, CI Smoke Tests). The name is what you will read in the revoke dialog at 2 a.m. someday.
3. Description — optional, up to 500 characters. Use it to record which application or pipeline the key serves.
4. Organization — choose which org owns the key. If you are an admin/owner of more than one, switch carefully here.
5. Projects — at least one project is required. Select the smallest set the consuming application actually needs. Keys cannot access scenes outside this selection.
6. Expiration — 30, 60, 90 days, or never. Default is 90. We recommend never picking "never" for keys that ship to client-side code.

When you click Create API Key, the platform generates a token and shows you the full plaintext exactly once in a one-time dialog.

Treat that screen as the only chance you will get. After you close it the platform retains a hashed copy and a four-character preview (…aB7Q); the plaintext is no longer recoverable. If you misplace it, you create a new key and revoke the old one.

How a Key Is Used in a Request#

Vectreal API keys travel in the standard HTTP Authorization header as Bearer tokens:

GET /api/scenes/<scene-id> HTTP/1.1
Host: vectreal.com
Authorization: Bearer vctrl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

On the server side, three checks happen on every request:

1. Format — token must start with vctrl_ and parse cleanly.
2. Domain — the request's Origin (or Referer) must match the project's allowed-domain patterns. Localhost is allowed by default for development; production hosts must be added explicitly.
3. Project membership — the scene the request is for must belong to a project this key was scoped to at creation.

A failure on any layer rejects the request, and repeated failures from the same client identifier are rate-limited (60 attempts per minute per origin IP).

That last point matters for one practical reason: a casual leak — a key showing up in a client-side bundle that the leaker uploads to GitHub — does not automatically translate to abuse. Without an allowed origin, a request still fails. The allowlist is the layer that converts a stolen key into a useless string.

Three Rotation Patterns That Match Real Deployments#

Most teams ship one of three shapes. Pick the one closest to you and the rotation cadence falls out.

1. Single marketing site (one origin, one key)#

You have one production website embedding a handful of Vectreal scenes. The key lives in the page's HTML or a server-side template.

• Issue: one key, scoped to the project that holds your marketing scenes.
• Domains: allow only your production domain (and your staging domain if you preview there).
• Expiration: 90 days.
• Rotation: every 60 days, mint the new key, ship the new build, revoke the old key after a 24-hour overlap.

This is the simplest pattern and the one most teams start with. It also benefits the most from setting an expiration — your future self will rotate the key on your behalf.

2. Per-environment application (dev / staging / prod)#

You have a real product. Engineers run scenes locally, your QA environment loads them on a staging domain, and prod is its own thing.

• Issue: three keys — one per environment.
• Domains: each key's project should allow only that environment's origin. localhost is fine on the dev key; do not allow it on prod.
• Expiration: 30 days for dev, 60 for staging, 90 for prod. Tighter on the keys most likely to leak (dev) and looser on the one with the most rotation cost (prod).
• Rotation: automate. The simplest version is a calendar event 14 days before expiration that creates a ticket assigned to whoever owns deploys.

The benefit of this layout is blast-radius control. A leaked dev key is annoying; a leaked prod key is an incident. Keeping them separate means revoking the wrong one does not take production down.

3. Per-tenant SaaS (one Vectreal project per customer)#

You are building a SaaS product where each of your customers gets their own Vectreal project (their own scenes, their own embed). You provision a Vectreal API key per customer at sign-up.

• Issue: one key per tenant, scoped to that tenant's project only.
• Domains: allow each tenant's domain on their own project. Your central marketing domain can stay on a separate key.
• Expiration: 90 days, with a renewal job in your provisioning workflow.
• Rotation: revocation becomes part of off-boarding. When a customer cancels, the revoke step is idempotent and immediate — embed traffic from their domain stops on the next request.

This is the layout most likely to grow past plan limits. The current per-org limits are 2 keys (Free), 10 (Pro), 50 (Business), unlimited (Enterprise). If you are crossing those thresholds at customer growth scale, the conversation is about tier rather than security model.

The Three Mistakes We See Most Often#

After months of helping teams launch, three patterns come up over and over.

1. One key shared across every site. A single "production" key embedded into half a dozen unrelated marketing sites. Convenient until one of them leaves the build, gets archived, and the key shows up in someone's browser cache six months later. Fix: one key per origin.

2. "Never expires" by default. Setting Never expires because it is the easiest option and then forgetting the key was ever created. Eighteen months later nobody remembers which application is using it, and rotating becomes a research project. Fix: pick 90 days. Future-you will thank you.

3. Wide-open project scope. Selecting all projects at creation because it was faster than checking. Now the key can read internal-only client work, prototype scenes, and the sales-demo project. Fix: smallest scope that works. You can always create a second, narrower key later — it is one click.

If you have shipped any of these, do not panic. Go to API keys, revoke the over-broad key, and create a replacement with the right scope. The revoke is immediate; the only client of the old key was your past habit.

Frequently Asked, Quickly Answered#

Can I share a key across organizations? No. Keys are bound to a single organization at creation.

Can a member without admin/owner role create or revoke keys? No. Both actions require the admin or owner role within the organization.

Where do I see who created a key? The API keys table shows the creator's name (or email) and creation date in the row metadata.

What does "revoke" do exactly? It marks the key inactive, immediately. Any application using it loses access on the next request. The action cannot be undone — you cannot un-revoke a key, only create a new one.

What happens to embedded scenes if I revoke a key they depend on? They will fail to load on the next request. If you need overlap during rotation, mint the new key first, ship the new build that uses it, then revoke the old one once traffic has cut over. We typically suggest a 24-hour overlap window.

Are there usage analytics per key? The dashboard shows last-used timestamp per key today. Per-key request counts and per-domain breakdowns are on the roadmap.

Does the platform record API key activity for audit? Audit logs are an entitlement available on Business and Enterprise plans (org_audit_log). On Free and Pro plans you have the dashboard's last-used timestamp.

What This Unlocks Next#

You now have a key that is scoped, expiring, and bound to the origins you actually deploy from. The next moves:

• Embed the scene in your app. If you are integrating into React specifically, the React Viewer Integration walkthrough covers SSR-safe loading and the ModelProvider pattern.
• Tighten the second layer. Open your project's Embed domain allowlist and remove any wildcard or development hosts that snuck in during testing. The allowlist is what saves you when a key leaks.
• Schedule the rotation. Whichever of the three patterns above matches you, put the next rotation on a calendar before you forget you read this.

If you are thinking about how to standardize this across a team that ships many embeds, talk to us. Vectreal is open-source, and our roadmap is public — security primitives like audit logs and per-key analytics get prioritized when teams tell us where the friction is.

Have a question or want to share how your team manages embed keys? Open a thread in our GitHub Discussions or join the conversation in Discord. The platform improves fastest when we hear from teams shipping it in production.

Vectreal is open-source under AGPL-3.0. The platform, viewer, hooks, and core packages live at github.com/vectreal/vectreal-platform.