API Keys & Secrets
API keys are not available on the Free plan, and the Embed Secret is available on the Business plan (see Plans Comparison). The page shows only what your plan includes, and is called API Keys or Secrets when it has just one of the two.
API keys are secret tokens that can be used to access Cluvio's API programmatically.
Every API key has a set of permissions that are tied to the API key's secret
token. To create a new API key, select New API Key.
The Key Type determines the available permissions for the key. With View,
the API key can only be assigned view permissions. Such API keys are thus always
read-only and cannot be used to perform changes on your Cluvio account. In
contrast, a Manage key can be assigned management permissions which allow the
API key to not only view resources in your Cluvio account but also to make
changes and even create new resources (datasources, dashboards, etc). An API
key's type is fixed on creation and cannot be changed later.
The API Version ties the API key to a specific version of the Cluvio API. At
the moment, the initial and only available API version is 2024-06-01. New API
versions are only introduced for backward-incompatible changes like the removal
of a request or response attribute, a change of behavior of an operation or even
the removal of an entire operation. An API key is tied to an API version for the
lifetime of the key. To transition to a newer API version when it becomes
available, create a new API key for the new version while keeping the old API
key until your application has been migrated to use the new API key.
Lastly, the Permissions determine which API operations are authorized for the
key. Refer to the Cluvio API Docs for the permissions needed for a
particular API operation.
When saving a new API key, the new API key's secret is generated and you are prompted to copy and store it for use by your application.
The API key secret must be kept private and secure. Typically it is stored in a protected configuration file for your backend application that integrates with the Cluvio API. The API key secret should not be embedded in JavaScript.
To view the secret of an existing API key, select the Show Secret action for
the API key in the list of API keys. You are asked to confirm your password first.
If you sign in with single sign-on, a window opens
instead in which you sign in with your identity provider again. After 10 wrong
passwords within 10 minutes, secrets are not shown until that time is up.
To edit an existing API key, click on the name in the list of API keys or choose
Edit from the API key's drop-down menu. Note that you can only edit the name
and permissions of an existing API key. Any change to an API key's permissions
takes effect immediately.
To temporarily deactivate or permanently delete an API key, use the drop-down menu available via the ⋮ (kebab) icon on the right of the API key in the list of keys. Deactivation or deletion of an API key takes effect immediately and API operations using a deactivated or deleted key will start failing.
Refer to the Cluvio API Docs to get started with using your API keys on the Cluvio public API.
Embed Secret
Every organization has an Embed Secret, which your backend uses to sign the
JWT tokens for embedding. The signed
JWT, the sharingSecret URL parameter on a sharing link, lets your backend
authorise embedded dashboards in a way that can't be tampered with.
The secret is not shown when the page loads. Select Show Secret on the
Current row and confirm your password, the same way as for an API key
secret, to see and copy it.
Reset Secret… in the Current row's ⋮ menu generates a new secret, for
example because the old one may have been compromised, or as a routine security
measure. The old secret then appears as the Previous row and keeps working
for 24 hours, until the time shown under Valid Until, so you can roll the
new secret out to your servers without an outage. Resetting does not show the
new secret; use Show Secret to copy it. Once your servers use the new secret,
Expire Now… in the Previous row's ⋮ menu stops the old one at once.
Never embed the Embed Secret directly in source code or store it in a client-side bundle. Read it from an environment variable on the server side (the code samples in Embedded Analytics show the idiomatic approach in seven languages).