Skip to main content

Bootstrap realm and service keys (self-hosted)

This page provisions a realm and service keys for a self-hosted Community deployment.

Prereqs​

  • You have a running self-hosted API and Postgres (see Install (self-hosted)).
  • You exported:
    • BILLING_MASTER_KEY
    • DATABASE_MIGRATOR_URI (superuser/owner connection string for provisioning)
    • VLUNA_PLANE (for OSS/Enterprise use vluna; admin reserved)
    • VLUNA_DB_SCHEMA (default control_plane)

What you will create​

  • A realm id (VLUNA_REALM_ID).
  • A service key id and derived secret:
    • VLUNA_SERVICE_KEY_ID
    • VLUNA_SERVICE_KEY_SECRET

Steps​

Run from vluna/oss:

cd vluna/oss
pnpm i
  1. List realms:
pnpm vlunactl realm list
  1. If you do not have a realm yet, create one:
pnpm vlunactl realm create \
  --realm-id realm-default \
  --name 'Demo Realm'

Optional metadata:

pnpm vlunactl realm create \
  --realm-id realm-default \
  --name 'Demo Realm' \
  --metadata-json '{
    "auth": {
      "issuers": [
        {
          "issuer": "https://issuer.example",
          "audiences": ["your-audience"],
          "jwks_uri": "https://issuer.example/.well-known/jwks.json"
        }
      ]
    },
    "payments": {
      "stripe": {
        "mode": "test",
        "api_keys": { "test": "sk_test_xxx" },
        "webhooks": [{ "name": "payment", "test": "whsec_xxx" }],
        "public_webhook_base_url": "https://example.com"
      }
    }
  }'
  1. Create a new service key id for the realm:
pnpm vlunactl service-key create --realm-id realm-default

Optional: create a key with an expiration time (ISO 8601):

pnpm vlunactl service-key create --realm-id realm-default --expires-at 2026-06-30T00:00:00Z
  1. Derive the service key secret for a specific key id:
pnpm vlunactl service-key secret \
  --realm-id realm-default \
  --key-id pk_example

Configure your integration environment​

Set these in the environment where your backend (or SDK examples) run:

export VLUNA_REALM_ID='realm-default'
export VLUNA_SERVICE_KEY_ID='pk_example'
export VLUNA_SERVICE_KEY_SECRET='base64_example'
export VLUNA_SERVICE_BASE_URL='https://us-central1.api.vluna.ai/mgt/v1'
export VLUNA_API_BASE_URL='https://us-central1.api.vluna.ai/api/v1'

When calling /mgt/v1 with this service key, include X-Realm-Id and set X-Realm-Admin: true if the request needs realm-wide admin RLS.

Verify​

Proceed to Verify installation and integration and run the smoke checks.

Security notes​

  • Keep VLUNA_SERVICE_KEY_SECRET server-side only. Never ship it to browsers or mobile apps.
  • Use a secret manager in production deployments. Do not hardcode secrets in source control.

Next steps​