About the Secrets API

The Secrets API contains functionality for managing secrets on a site. Secrets managed by this API are available in the Secrets Manager section of a site's dashboard. You can securely store API keys and other secrets on a 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 the Secrets Manager.

With the Secrets API, you can safely:

  • Create a secret.
  • Delete a secret.
  • Update a secret.
  • Retrieve a secret value.
  • Retrieve other information about your secrets, such as their names and descriptions.

Before you begin

It's important to note the following:

  • Before you can create or manage secrets with the Secrets API on a site, the site must have the Wix Members Area app installed. The Members Area isn't required to retrieve secrets with the Get Secret Value method.
  • 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.
  • To prevent malicious users from accessing the values of your secrets, use them only in backend code. Avoid using secret values in frontend code.
  • When developing websites or using Blocks, don't call List Secret Info in a .web.js file with anonymous permissions. This is a serious security risk which exposes your secrets to potential leaks. To prevent this, call List Secret Info in a separate .js file to block frontend access. If you must call List Secret Info in a .web.js file, make sure the exported function has permissions set to Admin.

Use Cases

  • Get an API key and use it to fetch information from a weather service.

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 key is a unique code used to authenticate a user or program when making a call to an API.
Did this help?

Secrets: Sample Use Cases and Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation.

Get an API key and use it to fetch information from a weather service

This use case demonstrates how you can store an API key from a weather service (for example, https://openweathermap.org/), and then use it to fetch the weather information to display on a site.

To get the weather data:

  1. Call Create Secret to store your API key you received after signing up on the OpenWeather site.

  2. Call Get Secret Value, assign the returned value to a variable, and make an OpenWeather API call. For example:

    Copy
    https://api.openweathermap.org/data/2.5/weather?q=London&units=metric&APPID={WEATHER_KEY}
  3. Extract the required values from the returned JSON object and display them on a site.

Did this help?

Secret Object


Properties
idstringRead-onlyformat GUID

Secret ID.


namestringmaxLength 50

A unique, human-friendly name for the secret. Use it to retrieve the secret value easily with the Get Secret Value endpoint.

Note: You can use alphanumeric characters and the following special characters: _+=-@#$. Spaces are not supported.


descriptionstringmaxLength 200

An optional text describing the secret's purpose or any other notes about it.


valuestringminLength 1maxLength 3500

The encrypted confidential value.


createdDatestringRead-onlyformat date-time

Date and time when the secret was created.


updatedDatestringRead-onlyformat date-time

Date and time when the secret was updated.

Secret
JSON
{ "secret": { "id": "a560ff70-3e9b-41b6-b66d-cf3434085f7d", "name": "secret_key", "description": "AWS secret access key", "value": "Fm8OfflH6bJOwWjenqAtLurLbkiMNvmhQHZV+118" } }
Did this help?

GET

Get Secret Value


Retrieves a secret value by name.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Secrets
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets/name/{name}

Path Params
namestringRequired

Secret name.

Response Object
valuestring

The plaintext, unencrypted value of the secret.

Get Secret Value Example 1
Request
cURL
curl -X GET 'https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets/name/secret_key' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \
Response
JSON
{ "value": "Fm8OfflH6bJOwWjenqAtLurLbkiMNvmhQHZV+118" }
Did this help?

GET

List Secret Info


Retrieves a list of secrets.

Note: This endpoint doesn't return the secret's value for security reasons. To retrieve the value, call Get Secret Value.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Secrets
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets

Request
This endpoint does not take any parameters.
Response Object
secretsArray <Secret>

A list of secrets with encrypted values.

List Secret Info Example 1
Request
cURL
curl -X GET 'https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \
Response
JSON
{ "secrets": [ { "id": "a560ff70-3e9b-41b6-b66d-cf3434085f7d", "name": "secret_key", "description": "AWS secret access key", "createdDate": "2024-09-12T12:32:15.000Z", "updatedDate": "2024-09-12T12:32:15.000Z" } ] }
Did this help?

POST

Create Secret


Creates a secret.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Secrets
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets

Body Params
secretSecretRequired

Details of a secret.

Response Object
idstring

Secret ID.

Create Secret Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ "secret": { "name": "secret_key", "description": "AWS secret access key", "value": "Fm8OfflH6bJOwWjenqAtLurLbkiMNvmhQHZV+118" } }'
Response
JSON
{ "id": "a560ff70-3e9b-41b6-b66d-cf3434085f7d" }
Event TriggersThis method triggers the following events:
Did this help?

DELETE

Delete Secret


Deletes a secret.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Secrets
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets/{id}

Path Params
idstringRequired

ID of the secret to delete.

Response Object
Returns an empty object.
Delete Secret Example 1
Request
cURL
curl -X DELETE 'https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets/a560ff70-3e9b-41b6-b66d-cf3434085f7d' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Partially Update Secret


Updates 1 or all fields of a secret.

To get the secret ID, call List Secret Info.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Secrets
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets/{id}

Path Params
idstringRequired

ID of the secret to update.

Body Params
secretSecretRequired

Details of a secret.

Response Object
Returns an empty object.
Partially Update Secret Example 1
Request
cURL
curl -X PATCH 'https://www.wixapis.com/_api/cloud-secrets-vault-server/api/v1/secrets/a560ff70-3e9b-41b6-b66d-cf3434085f7d' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ "secret": { "name": "updated_secret_key", "description": "AWS secret access key", "value": "44aSQCljxL9FLvTVA.9dKbpwueYoQ8isyQhvun19pOT9gHEdgxam39LJ0Ts70" } }'
Response
JSON
{}
Event TriggersThis method triggers the following events:
Did this help?

Secret Created


Triggered when a secret is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.velo.secrets_vault.v1.secret.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.velo.secrets_vault.v1.secret_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

SecretCreated
JSON
{ "id": "9aca3895-8c58-48b7-84a5-35bcd431c125", "entityFqdn": "wix.velo.secrets_vault.v1.secret", "slug": "created", "entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0", "createdEvent": { "entity": { "id": "a560ff70-3e9b-41b6-b66d-cf3434085f7d", "name": "secret_key", "description": "AWS secret access key", "value": "Fm8OfflH6bJOwWjenqAtLurLbkiMNvmhQHZV+118" } }, "eventTime": "2023-05-25T11:39:26.278160Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "1" }
Did this help?

Secret Deleted


Triggered when a secret is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.velo.secrets_vault.v1.secret.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.velo.secrets_vault.v1.secret_deleted", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

SecretDeleted
JSON
{ "id": "9aca3895-8c58-48b7-84a5-35bcd431c125", "entityFqdn": "wix.velo.secrets_vault.v1.secret", "slug": "deleted", "entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0", "deletedEvent": {}, "eventTime": "2023-05-25T11:39:26.278160Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "1" }
Did this help?

Secret Updated


Triggered when a secret is updated.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.velo.secrets_vault.v1.secret.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.velo.secrets_vault.v1.secret_updated", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

SecretUpdated
JSON
{ "id": "9aca3895-8c58-48b7-84a5-35bcd431c125", "entityFqdn": "wix.velo.secrets_vault.v1.secret", "slug": "updated", "entityId": "aaf51c30-a61c-473e-96be-a42dfa5064c0", "updatedEvent": { "entity": { "id": "a560ff70-3e9b-41b6-b66d-cf3434085f7d", "name": "updated_secret_key", "description": "AWS secret access key", "value": "44aSQCljxL9FLvTVA.9dKbpwueYoQ8isyQhvun19pOT9gHEdgxam39LJ0Ts70" } }, "eventTime": "2023-05-25T11:39:26.278160Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "1" }
Did this help?