# Secrets

Secrets allow you to securely store credentials and sensitive values — such as API tokens, usernames and passwords, or JSON configuration — for use in integrations and notification templates. Secret values are encrypted and stored securely. Once saved, values cannot be viewed again and are only accessible at the time of use.

Secrets are available in the platform to **Org Admin** and **Domain Admin** users. They can be managed by navigating to the **Domain Settings** page and selecting the **Security** tab. The **Secrets** section is located below **API Tokens**.

The **Secrets** list displays the following columns: **Alias**, **Type**, **Last Updated Date**, and **Actions**.

<figure><img src="https://810756845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lry9Z27iWOZyQEGAgY7%2Fuploads%2FonYuOSkmQbxa6WWMyb32%2FScreenshot%202026-03-06%20at%208.12.13%E2%80%AFAM.png?alt=media&#x26;token=941431e1-05f3-4417-b32b-84a3e65143b2" alt=""><figcaption></figcaption></figure>

**Creating a New Secret**

From the **Security** tab, locate the **Secrets** section and click the **Add Secret** button. A **Create secret** drawer will slide out from the right with the following fields:

* **Alias** — A unique name for the secret (e.g., `weather_fx`). Aliases are case-insensitive and must contain only lowercase letters, numbers, hyphens, and underscores.
* **Secret Type** — Select the type of secret you want to store:
  * **Token** — A single string value such as an API key.
  * **Username and password** — A pair of credentials.
  * **JSON** — A JSON key-value configuration object.
* **Value** — The input fields change based on the selected secret type:
  * **Token**: A single masked input field.
  * **Username and password**: A username text field and a masked password field.
  * **JSON**: A code editor with JSON validation.

Click the **Submit** button to save the secret.

> ⚠️ Secret values are write-only. Once created, you will not be able to view the stored value. Ensure your credentials are saved elsewhere before submitting.

<figure><img src="https://810756845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lry9Z27iWOZyQEGAgY7%2Fuploads%2FPTKhpatdHwrvDbSKV1Vq%2FScreenshot%202026-03-06%20at%208.11.49%E2%80%AFAM.png?alt=media&#x26;token=f8630b7a-0de4-492a-92cc-ae963edfebed" alt=""><figcaption></figcaption></figure>

**Editing a Secret**

To update the stored value of an existing secret, click the **Edit** action on the secret's row in the list. The edit drawer will appear with the **Alias** and **Secret Type** fields locked. Enter the new value and click **Submit** to rotate the stored credentials.

This is useful when you need to rotate an API key or update a password without changing the alias that is already referenced in your templates or integrations.

**Archiving a Secret**

To remove a secret, click the **Archive** action on the secret's row. A confirmation dialog will appear with the message:

> "Are you sure you want to archive this secret? Any existing integrations using this secret will no longer function."

Click **Archive Secret** to confirm, or **Cancel** to go back. Archived secrets are removed from the list and can no longer be used in integrations or templates.

**Using Secrets in Templates**

Secrets can be referenced in notification templates and integrations using the **Macro Manager**. When building a template, open the Macro Manager and select the **Secrets** category. Choosing a secret will insert the reference into your template using the format:

```
secrets.<alias>
```

For example, if you created a secret with the alias `weather_fx`, you would reference it as `secrets.weather_fx`. At send time, the platform will securely resolve the secret value without exposing it in the template editor.