Introduction

Velo's Secrets Manager allows you to securely store API keys and other secrets on your site. Each secret's value is encrypted, and assigned a name of your choice and an ID. You can then use the name or ID to refer to the secret in your backend code rather than hardcoding its value.

Learn more about Velo's Secrets Manager.

With the Secrets API, you can safely:

  • Manage secrets.
  • Retrieve secret values.
  • Retrieve other information about your secrets, such as their names and descriptions.

To use the Secrets API, import wixSecretsBackend from the wix-secrets-backend module:

Copy
import wixSecretsBackend from "wix-secrets-backend";

Learn more about the Wix Secrets API in Secrets Manager in the Velo API Reference, and on Wix Learn.

Before you begin

It's important to note these points before coding:

  • You must set up a Members Area, before you can create or manage secrets with the Secrets API. The Members Area isn't required to retrieve secrets with getSecret().
  • Deleting a secret, or modifying a secret's name or value, breaks all code using the secret.
  • You can't create or rename a secret with a name that's already in use.

Security considerations

  • If you currently use private keys in your code, we recommend removing them. You can either create a secret with the Secrets API or the Functional Testing tool.
  • To prevent malicious users from accessing the values of your secrets, use them only in backend code. Avoid using secret values in client side code.

Terminology

  • Secret: Secrets are values that you don’t want to be publicly accessible, such as login credentials or API keys.
  • API key: An API (Application Programming Interface) key is a unique code used to authenticate a user or program when making a call to an API.
Did this help?

Sample Flow

Follow this general procedure for working with API keys or other secrets using the Secrets Manager:

  1. Get private information such as an API key from a 3rd-party service.
  2. Store the private information as a new secret in the Secrets Manager in your site's dashboard or with the createSecret() function. Assign a name to the secret.
  3. In your backend code, instead of hardcoding the API key, use the getSecret() function with the secret name assigned in the Secrets Manager. When the code runs, the value of the secret is extracted from the Secrets Manager.
Did this help?

createSecret( )


Creates a new secret.

The createSecret() function returns a Promise that resolves to the newly created secret's ID when a secret has been created in the Secrets Manager. Secrets created by this function are available in the Secrets Manager section in your site's dashboard, just like any other secret created using the UI.

Note:

  • The secret's name cannot start with wix or be identical to an existing secret's name.

  • Do not leave private keys in your code! Leaving them in is a security risk. Either delete the keys from the code after running createSecret(), or pass the parameters in using the Functional Testing tool.

Method Declaration
Copy
function createSecret(secret: Secret): Promise<string>;
Method Parameters
secretSecretRequired

The object including the fields of a new secret to be stored.

Returns
Return Type:Promise<string>
Create a new secret
JavaScript
import { Permissions, webMethod } from "wix-web-module"; import wixSecretsBackend from "wix-secrets-backend"; export const createNewSecret = webMethod(Permissions.Anyone, () => { const secret = { name: "s3_secret_key", value: "Fm8OfflH6bJOwWjenqAtLurLbkiMNvmhQHZV+118", description: "AWS secret access key", }; return wixSecretsBackend .createSecret(secret) .then((id) => { return id; }) .catch((error) => { console.error(error); }); }); /* * Returns a Promise that resolves to: * * "5ec36ffb-2cec-489a-9c0e-d8f53fef5fd1" */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

deleteSecret( )


Deletes an existing secret by ID.

The deleteSecret() function returns a Promise that resolves when a secret from the Secrets Manager is deleted. You can retrieve the id parameter using the listSecretInfo() function. Note that the ID used here is the ID retrieved from listSecretInfo(), not the secret name used by getSecret().

Note: Deleting a secret is irreversible and will break all code using the secret.

Method Declaration
Copy
function deleteSecret(id: string): Promise<void>;
Method Parameters
idstringRequired

The ID of the secret to be deleted.

JavaScript
import { Permissions, webMethod } from "wix-web-module"; import wixSecretsBackend from "wix-secrets-backend"; export const deleteMySecret = webMethod(Permissions.Anyone, () => { const id = "b741766c-eead-46fe-8e7f-fd01ff3d6e21"; return wixSecretsBackend .deleteSecret(id) .then(() => { console.log("Secret deleted"); }) .catch((error) => { console.error(error); }); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getSecret( )


Gets a secret by name.

The getSecret() function returns a Promise that resolves to the value of the secret that was stored in the Secrets Manager with the given name.

Note: To prevent malicious users from accessing the value of your secret, don't return the value of the secret to client side. Only use the secret's value in the backend.

Method Declaration
Copy
function getSecret(name: string): Promise<string>;
Method Parameters
namestringRequired

The name of the secret to get the value of.

Returns
Return Type:Promise<string>
JavaScript
import { Permissions, webMethod } from "wix-web-module"; import wixSecretsBackend from "wix-secrets-backend"; import { getJSON } from "wix-fetch"; export const getSomeJSON = webMethod(Permissions.Anyone, () => { return wixSecretsBackend .getSecret("myApiKeyName") .then((secret) => { return getJSON(`https://someapi.com/api/someendpoint?apiKey=${secret}`); }) .catch((error) => { console.error(error); }); }); export const getFirstSecretValue = webMethod(Permissions.Anyone, () => { return wixSecretsBackend .listSecretInfo() .then((secrets) => { return wixSecretsBackend.getSecret(secrets[0].name); }) .catch((error) => { console.error(error); }); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

listSecretInfo( )


Gets a list of objects containing information about all secrets stored in the Secrets Manager.

The listSecretInfo() function returns a Promise that resolves to a list containing information about all secrets stored on your site. The secret's value is omitted for security reasons, and can be retrieved using the getSecret() function for each individual secret.

Note: Do not use listSecretInfo() in a .jsw file with anonymous permissions! This is a serious security risk which exposes your secrets to potential leaks. To prevent this, implement listSecretInfo() in a separate .js file to block frontend access. If you must include listSecretInfo() in a .jsw file, make sure the exported function has permissions set to Admin.

Method Declaration
Copy
function listSecretInfo(): Promise<Array<SecretInfo>>;
Request
This method does not take any parameters
Returns
Return Type:Promise<Array<SecretInfo>>
JavaScript
import wixSecretsBackend from "wix-secrets-backend"; export function getSecretInfo() { return wixSecretsBackend .listSecretInfo() .then((secrets) => { return secrets; }) .catch((error) => { console.error(error); }); } /* Returns a Promise that resolves to: * * [ * { * "id": "2eebccce-6c01-469d-a278-433fd96ba111", * "createdDate": "2020-05-26T06:16:46.000Z", * "updatedDate": "2020-05-28T12:21:10.000Z", * "name": "MyFirstSecret", * "description": "This is my first secret" * }, * { * "id": "ef4b43d4-851d-4b52-a07f-9a500a888371", * "createdDate": "2020-06-02T08:23:54.000Z", * "updatedDate": "2020-06-02T08:23:54.000Z", * "name": "MySecondSecret", * "description": "This is my second secret" * } * ] */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

updateSecret( )


Updates the specified fields of an existing secret by ID.

The updateSecret() function returns a Promise that resolves when the secret is successfully updated. You can update one or more secret properties. Only the properties passed in the Secret object will be updated. All other properties will remain the same. You can retrieve the id parameter from the listSecretInfo() function. The id is not the same as the secret name used by the getSecret() function.

Notes:

  • Changing a secret's name or value will break all code using the secret.

  • You cannot rename the secret with a name that is already in use.

  • Do not leave private keys in your code! Leaving them in is a security risk. Either delete the keys from the code after running updateSecret(), or pass the parameters in using the Functional Testing tool.

Method Declaration
Copy
function updateSecret(id: string, secret: SecretUpdateInfo): Promise<void>;
Method Parameters
idstringRequired

The ID of the secret to update.


secretSecretUpdateInfoRequired

The information to update the secret with.

JavaScript
import { Permissions, webMethod } from "wix-web-module"; import wixSecretsBackend from "wix-secrets-backend"; export const updateName = webMethod(Permissions.Anyone, () => { const id = "b741766c-eead-46fe-8e7f-fd01ff3d6e21"; const secret = { name: "my_new_secret_name", }; return wixSecretsBackend .updateSecret(id, secret) .then(() => { console.log("Secret name updated"); }) .catch((error) => { console.error(error); }); });
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?