Security model

This document details Vespa Cloud's security model.

For use of keys in automation, refer to examples in automated deployments and the api key reference.


User API Key

Control plane

This key is used to access the Vespa Cloud control APIs. The key is set on the tenant level - it is hence valid for all applications for the tenant. The key is associated with a user and can be uploaded or generated in the "Keys" view in the Console.

Use this key to deploy/submit applications with Maven (see getting started, including Java development).

This key has full control plane read/write credentials.

Application API Key

Control plane

This key is used to access the Vespa Cloud control APIs. The key is associated with an application, and can be uploaded or generated in the "Application deploy" view in the Console.

Use this key in CI/CD pipelines where headless access is required to deploy applications.

This key has control plane read credentials, and also deploy/submit rights.

Vespa API Certificate

Data plane

The key is a private key and X.509 certificate generated for the client. Only clients using the private key and certificate will be granted access to the application's data plane. Example data plane APIs are query, feed and metrics.

Generate the certificate and key and include the certificate in the application package - example: create a self-signed certificate.

Control plane

The following explains how access to management features in Vespa is controlled.


Console access is available to authenticated users only. This is bootstrapped by creating a tenant. Manage users and roles in the users view:


Can create applications, deploy to dev zones and submit to prod zones.


Manage users and tenant information. Tenant information includes usage information and billing.

Application deployment

There are two kinds of application deployments:

Likewise, there are two kinds of keys that can be used for API authentication:

  • User API keys, which identify a member of the developer role, and allows, e.g., manual deployments and system tests, and

  • application API keys, which identify a build service which submits application packages for automated deployment.

User API keys are personal, and are managed in the users view. Each developer may have a single key at any time, and both administrators and developers may revoke the key of another developer, if it has been compromised.

Application API keys are managed on the application level - see deploy view. An application can have multiple Application API keys.

Refer to the api key reference for details.

Data plane

All application endpoints are secured with mutual TLS.

Server certificate

On first time deployment, a server certificate identifying the application is provisioned. This certificate will be automatically set up on all application endpoints. The certificate is signed by DigiCert or Globalsign.

Client certificate

To enable TLS client side authentication, add trusted certificates (or issuer certificates) to [application-package]/security/clients.pem With this, only clients with a valid certificate can access the application endpoints.

In order to test application deployments, another trusted client certificate is added by Vespa Cloud for deployment to the test and staging zones only. This does not affect production deployments.

To run system tests against a development endpoint, specify the dataPlaneCertificateFile and dataPlaneKeyFile properties, in the same manner as the apiKeyFile used for API access.

To add a new certificate/key pair:

  1. Generate a new pair. Example:

    $ openssl req -x509 -nodes -days 365 -newkey rsa:4096 \
      -subj "/CN=cloud.vespa.example" \
      -keyout data-plane-private-key.pem -out data-plane-public-cert.pem
  2. Add new public certificate to application package (it is OK with blank lines in clients.pem - example):

    $ cat data-plane-public-cert.pem >> src/main/application/security/clients.pem
  3. Deploy the application package.

  4. Use new cert/key pair in Vespa requests.

  5. Remove unused certs from clients.pem and deploy again.

Using a browser

In Vespa guides, curl is used in examples, like:

$ curl --cert ./data-plane-public-cert.pem --key ./data-plane-private-key.pem $ENDPOINT

To use a browser, install key/cert pair - this procedure is tested on macOS Catalina / Chrome 80.0.3987.132, assuming Certificate Common Name is "cloud.vespa.example" (as in the guides):

  1. Install key/cert pair:

    $ security import data-plane-private-key.pem -k ~/Library/Keychains/login.keychain
    $ security import data-plane-public-cert.pem -k ~/Library/Keychains/login.keychain
  2. In Keychain Access: With login keychain -> My Certificates category -> cloud.vespa.example, right-click and "New Identity Preference", then add the endpoint url, like

  3. Open the same URL in Chrome, choose the certificate and allow Chrome to read the private key.

Application isolation

All application nodes run as separate isolated Docker containers.

All internal communication between nodes in an application is secured in two layers:

  • Network ACLs (iptables) allowing only local communication within the application.

  • Mutual TLS with authorization only allowing nodes from the same application.