# Secrets

Secrets are a secure way to store and maintain sensitive values (e.g. credentials or API tokens) for use in [lifecycle scripts](/sandboxes/lifecycle-scripts.md). Secrets are write-only, which prevents all users from reading their values. Secrets are defined on team level, allowing them to be used by multiple tracks. 

{% hint style="info" %}
Secrets can only be created/updated by team Owners, and can be used by Content Creators.
{% endhint %}

## View secrets

Follow the steps bellow to access the Secret management page.

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Secrets**.
2. A table will show detailing all your teams current Secrets
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Open a new terminal.
2. Enter the following command:

   ```
   instruqt secrets list
   ```

   ↳ Instruqt CLI lists all secrets for the currently configured team. \
       The output looks something like this:

   ```xml
   ==> Listing secrets for team TEAM_NAME
       NAME              CREATED                 UPDATED                 DESCRIPTION
       SECRET_KEY_1      2022-08-16T13:43:43     2022-08-16T13:43:43     Description of secret one
       SECRET_KEY_2      2022-08-16T13:44:23     2022-08-16T15:23:06     Description of secret two

   ```

{% endtab %}
{% endtabs %}

## Add a secret

Follow the steps below to add a new secret to your team. 

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Secrets**.
2. Click the **Create** button on the top right of the page 
3. In the **Name** field, enter a name or key of the secret. Secrets only accept letters, numbers and underscores (e.g. **MY\_SECRET\_KEY**).
4. In the **Description** field, enter a description of the secret.
5. In the **Value** field, enter the actual secret value.
6. Click **Save Changes**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Open a new terminal.
2. Enter the following command:

   ```
   instruqt secrets create SECRET_NAME "SECRET_VALUE" \ 
       --description="SECRET_DESCRIPTION"
   ```

   ⇨ Replace `SECRET_NAME` with the name of the secret you would like to create.\
   ⇨ Replace `SECRET_VALUE` with the value of the secret.\
   ↳ Instruqt CLI creates the new secret. The output looks something like this:

   ```xml
   ==> Create secret SECRET_NAME for team TEAM_NAME
       OK
   ```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
The description should help content creators understand how the Secret should be used. It's recommend to keep the descriptions brief but indicative of how the secret should be used.
{% endhint %}

## Update a secret

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Secrets**.
2. Click  ••• on the secret you would like to update and select **Update.**
3. In the **Description** field, enter a new description if applicable.
4. In the **Value** field, enter the new secret value, this is mandatory for updates.
5. Click **Save changes**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Open a new terminal.
2. Enter the following command:

   ```
   instruqt secrets update SECRET_NAME "SECRET_VALUE" 
   ```

   ⇨ Replace `SECRET_NAME` with the name of the secret you would like to create.\
   ⇨ Replace `SECRET_VALUE` with the value of the secret.\
   ↳ Instruqt CLI creates the new secret. The output looks something like this:

   ```xml
   ==> Update secret SECRET_NAME for team TEAM_NAME
       OK
   ```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
When updating a Secret the value is always required. If you would like update the description only the previous secret value should be used. 
{% endhint %}

## Delete a secret

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Settings -> Secrets**.
2. Click  ••• on the secret you would like to delete and select **Delete.**\
   ↳ A delete confirmation is shown
3. Click **Confirm**.\
   ↳ The secret is deleted and removed and not available on the secrets table.  
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Open a new terminal.
2. Enter the following command:

   ```
   instruqt secrets delete SECRET_NAME 
   ```

   ⇨ Replace `SECRET_NAME` with the name of the secret you would like to delete.\
   ↳ Instruqt CLI creates the new secret. The output looks something like this:

   ```xml
   ==> Delete secret SECRET_NAME for team TEAM_NAME
       OK
   ```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Once a Secret has been deleted it will not be possible to recover the value that was previously stored. 
{% endhint %}

## Add secrets to tracks

To make use of a Secret value in a tracks [lifecycle scripts](/sandboxes/lifecycle-scripts.md) the track must to be granted access to the secret. 

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click the track to which you want to give secret access.
2. In the **Sandbox** section, click **Edit** to open the *Sandbox page*.
3. Click **+ Add a secret**.
4. Select the secrets you would like access in your track scripts by clicking the checked box.
5. Click **Save**.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}
Add the following code into `config.yml`, where `SECRET_NAME` is the name of the secret you would like to make use of in the tracks lifecycle scripts.

```yaml
secrets:
- name: SECRET_NAME
```

↳ Your `config.yml` file should be similar to this:

```yaml
version: "3"
secrets:
- name: MY_SECRET_KEY
- name: ANOTHER_SECRET_KEY
```

{% endtab %}
{% endtabs %}

Adding a Secret to your track sets an environment variable which is available for the duration of a tracks [lifecycle scripts](/sandboxes/lifecycle-scripts.md).

#### Example

Consider the following example, making an authorised *curl* request using a username and password:\
\
1\. Add a Secret with `SITE_PASSWORD` as the name and the password as the value.

2\. Add the following to your lifecycle script:

```bash
curl --user name:${SITE_PASSWORD} http://www.example.com
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/sandboxes/runtime/secrets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.