Set up the public API service

Vera 2026.1 introduces a new service, vera-api-public, that powers the public API. You need to add this service to your deployment before administrators can issue API keys and integrators can make requests. This topic covers what to add, how to configure the required secret, and how to verify that the service is running.

For background on how the public API works from the user's perspective, see Vera public API.

Before you start

Before you deploy the public API service, confirm the following:

  • You have access to your Vera deployment configuration (Docker Compose or Helm chart).

  • You have a secrets manager or a secure method to inject environment variables into your containers.

  • Your MongoDB instance is running and accessible to other Vera services. The new service uses the same MongoDB instance as the rest of Vera.

Add the service to your deployment

Add vera-api-public to your deployment alongside the existing Vera services. The service follows the same container and health check patterns as other vera-api-* services in your stack.

For Docker Compose deployments, download the updated docker-compose_2026_1.yml file, which includes the vera-api-public service definition. For Helm deployments, update your chart values to include the new service according to your chart's documentation.

The service exposes liveness and readiness endpoints that follow the same pattern as other Vera services. Add health checks to your deployment configuration accordingly.

Configure the required secrets

The vera-api-public service requires two secrets: a dedicated client secret to authenticate with the Vera identity server, and a pepper used to hash API keys. Both secrets are separate from the internal client secrets used by other services. Use unique values per environment.

Set the following environment variables for the vera-api-public service before you start it:

Variable

Description

VERA_CLIENT_SECRET_PUBLIC_API

The client secret for the public_api_service identity server client. Generate a unique value for each environment. If you use External Secrets, the corresponding key in your app-secrets JSON is VeraClientSecretPublicApi.

VERA_API_KEY_PEPPER

A secret used to hash API keys. The value must match between the vera-api-public service and the Vera Server. If the values don't match, key validation fails and integrators can't authenticate.

The service won't start if either variable is missing or empty. Set both before you bring the stack up.

For a full list of supported environment variables, see Supported environment variables.

Configure network and ingress

Expose the /api/v1/ path from vera-api-public to your integrators. Keep the admin API key management traffic off the public internet if your architecture separates portal traffic from public API traffic. This traffic goes through the web portal backend.

If you use a reverse proxy or load balancer in front of your Vera services, add a routing rule for /api/v1/ that targets the vera-api-public service.

Configure IP allowlists

The public API supports per-key IP allowlists that administrators configure from the web portal. For these to work correctly when your deployment sits behind a proxy, you need to forward the original client IP to the vera-api-public service.

Configure your proxy to pass the client IP using X-Forwarded-For or the equivalent header for your proxy. Set the number of trusted proxy hops so the service reads the correct IP from the header chain and doesn't trust injected values from untrusted sources.

If you don't use IP allowlists, you can skip this step.

Verify the deployment

After you bring up the updated stack, confirm that the vera-api-public service is healthy:

  1. Check the container logs for startup errors. The service logs at the same level as other Vera services.

  2. Send a request to the liveness endpoint. A successful response confirms the service started correctly.

  3. In the Vera web portal, go to Administration > API Keys and confirm the page loads. If the page is missing, the service may not have registered correctly with the rest of the stack.

Upgrade notes

If you're upgrading an existing Vera deployment to 2026.1, you need to add vera-api-public as a new service. It doesn't replace any existing service. Also check for the following:

  • Set VERA_CLIENT_SECRET_PUBLIC_API and VERA_API_KEY_PEPPER in your secrets configuration before the upgrade completes. The service fails to start without them, and the pepper value must match the one configured on Vera Server.

  • MongoDB may require new indexes for the API key metadata collection. These are applied automatically on first startup.

  • Update your Docker Compose or Helm chart to include the new service definition from the 2026.1 release files.

For general upgrade steps, see Upgrade to 2026.2.

What's next

Now that the service is running, here's what you can do next: