Security

By default, all endpoints of a VCR application are publicly accessible. The security block in vcr.yml lets you control access per-path using three access levels and optional authentication enforcement.

It is strongly recommended to configure security rules for all endpoints in your application. Leaving endpoints unprotected exposes your application to unauthorized access, abuse, and unexpected costs. At minimum, set a restrictive default access level and explicitly open only the paths that need to be public (such as Vonage webhook callbacks).

Access Levels

Level Description
public No authentication required. Anyone can reach the endpoint.
private Not accessible from outside the platform. Only internal VCR services can call it.
authenticated Requires valid Vonage API credentials in the Authorization header (HTTP Basic: base64(api_key:api_secret)). The platform validates the credentials before forwarding the request to your application.

Configuration

instance:
    security:
        access: private
        override:
            - path: "/webhooks/*"
              access: public
            - path: "/api/**"
              access: authenticated
              auth-method: vonage_basic
  • access sets the default access level for all paths not matched by an override.
  • override is a list of path-specific rules. Rules are evaluated in order; the most specific match wins.
  • auth-method is required when access is authenticated. The only supported value is vonage_basic.

Path Wildcards

Wildcard Matches Example
* A single path segment /users/*/profile matches /users/123/profile but not /users/123/settings/profile
** Any number of path segments /api/** matches /api/v1, /api/v1/users, /api/v1/users/123, etc.

Webhook Endpoints Require Unrestricted Access

Vonage platform callbacks (inbound calls, inbound messages, delivery receipts, etc.) originate from outside your instance. These endpoints must be set to public, otherwise the Vonage platform cannot reach them and your providers will not receive events.

instance:
    security:
        access: private
        override:
            - path: "/onCall"
              access: public
            - path: "/onMessage"
              access: public
            - path: "/api/**"
              access: authenticated
              auth-method: vonage_basic

How Authenticated Access Works

When a request hits an authenticated path, the traffic controller:

  1. Checks that an Authorization header is present. If missing, returns 401 Unauthorized.
  2. Validates the credentials against Vonage's auth service and confirms the caller belongs to the same Vonage account as the instance owner. If invalid or mismatched, returns 403 Forbidden.
  3. If validation passes, forwards the request to your application unchanged.

The vonage_basic auth method uses HTTP Basic authentication. The caller must send their Vonage API key and API secret encoded as a Basic auth credential:

Authorization: Basic base64(api_key:api_secret)

Most HTTP clients handle this automatically when you supply a username and password:

// Example: calling an authenticated VCR endpoint from a client
const response = await fetch('https://my-app.use1.runtime.vonage.cloud/api/data', {
  headers: {
    'Authorization': 'Basic ' + btoa(`${API_KEY}:${API_SECRET}`),
  },
});

Your application code does not need to validate the credentials itself — the platform enforces authentication before the request reaches your handler. If you need to identify the caller inside your handler, the platform injects the verified account ID via the x-neru-apiaccountid header:

app.get('/api/data', async (req, res) => {
  const accountId = req.headers['x-neru-apiaccountid'];
  res.json({ accountId });
});

Auth Method Inheritance

If an override entry sets access: authenticated but omits auth-method, it inherits the top-level auth-method value. If neither is set, the deployment API will reject the configuration.

instance:
    security:
        access: public
        auth-method: vonage_basic   # inherited by all authenticated overrides
        override:
            - path: "/admin/**"
              access: authenticated  # uses vonage_basic from above
            - path: "/api/**"
              access: authenticated  # also uses vonage_basic from above