# Secrets

Secrets are a secure way to store and maintain sensitive values (e.g. credentials or API tokens) for use in [lifecycle scripts](https://docs.instruqt.com/sandboxes/lifecycle-scripts). 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](https://docs.instruqt.com/sandboxes/lifecycle-scripts) 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](https://docs.instruqt.com/sandboxes/lifecycle-scripts).

#### 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
```