API Keys

API keys are used to authenticate requests to the Vivreal API. Your website or application uses an API key to fetch published collections, objects, and media.

What API Keys Provide

An API key grants read-only access to your group's published content, plus the ability to create Stripe checkout sessions and send contact emails. The key is scoped to a single group and cannot access other groups' data.

Generating an API Key

Go to Group Settings

In the Vivreal portal, navigate to Group Settings from the dashboard.

Find the API Key section

Scroll to the API Access section. If a key already exists, it will be displayed (partially masked).

Generate or regenerate

Click Generate API Key to create a new key. If a key already exists, clicking Regenerate will invalidate the old key and issue a new one.

Copy and store securely

Copy the key immediately. It will not be shown in full again. Store it in your application's environment variables.

Regenerating invalidates the old key

When you regenerate an API key, the previous key stops working immediately. Update all applications using the old key before regenerating.

Using the API Key

Pass your API key in the Authorization header on every request:

cURL

curl "https://client.vivreal.io/tenant/siteDetails?siteId=YOUR_SITE_ID" \
  -H "Authorization: YOUR_API_KEY"

JavaScript (fetch)

const response = await fetch(
  "https://client.vivreal.io/tenant/collectionObjects?collectionId=YOUR_COLLECTION_ID",
  {
    headers: {
      Authorization: process.env.VIVREAL_API_KEY,
    },
  }
);

const { data } = await response.json();

JavaScript (axios)

import axios from "axios";

const client = axios.create({
  baseURL: "https://client.vivreal.io/tenant",
  headers: {
    Authorization: process.env.VIVREAL_API_KEY,
  },
});

const { data } = await client.get("/collectionObjects", {
  params: { collectionId: "YOUR_COLLECTION_ID" },
});

Security Best Practices

Never expose keys in client-side code

API keys should only be used in server-side code (Node.js, Next.js server components, API routes). Never include them in browser-accessible JavaScript bundles.

Store in environment variables — Use .env.local or your hosting platform's secrets manager. Never commit keys to version control.
Use server-side only — All API calls should happen in server components, API routes, or backend services.
Rotate periodically — Regenerate your API key on a regular schedule as a precaution.
Monitor usage — Watch your group's API call metrics in the dashboard to detect unexpected spikes that could indicate a leaked key.
One key per group — Each group has a single active API key. If you need different access patterns, use separate groups.

Usage Quotas

Each group has a monthly API call quota based on its tier:

Tier	API Calls/month	CDN Bandwidth/month
Free	1,000	1 GB
Basic	50,000	25 GB
Pro	500,000	100 GB
Pro Plus	2,000,000	500 GB

Exceeding either quota returns a 402 Payment Required response. Quotas reset on the first of each month (UTC). Enable overage billing in Group Settings to avoid being blocked — requests will be metered instead.

Troubleshooting

401 Unauthorized — The API key is missing, invalid, or has been regenerated. Verify the Authorization header value.
402 Payment Required — Your group's monthly API call or CDN bandwidth quota has been exceeded. Upgrade your tier or enable overage billing.
403 Forbidden — The group associated with the key may be frozen or suspended. Check your group status in the portal.