# Managing secrets

You can use secrets to interact with external services.

## Creating secrets

### Creating a secret on the command line

To create a secret, use the `union create secret` command:

```shell
$ union create secret my_secret_name
```

You'll be prompted to enter a secret value in the terminal:

```
Enter secret value: ...
```

### Creating a secret from a file

To create a secret from a file, run the following command:

```shell
$ union create secret my_secret_name -f /path/to/secret_file
```

### Scoping secrets

* When you create a secret without specifying a project` or domain, as we did above, the secret will be available across all projects-domain combinations.
* If you specify only a domain, the secret will be available across all projects, but only in that domain.
* If you specify both a project and a domain, the secret will be available in that project-domain combination only.
* If you specify only a project, you will get an error.

For example, to create a secret so that it is only available in `my_project-development`, you would run:

```shell
$ union create secret my_secret_name --project my_project --domain development
```

## Listing secrets

You can list existing secrets with the `union get secret` command.
For example, the following command will list all secrets in the organization:

```shell
$ union get secret
```

Specifying either or both of the `--project` and `--domain` flags will list the secrets that are **only** available in that project and/or domain.

For example, to list the secrets that are only available in `my_project` and domain `development`, you would run:

```shell
$ union get secret --project my_project --domain development
```

## Using secrets in workflow code

Note that a workflow can only access secrets whose scope includes the project and domain of the workflow.

### Using a secret created on the command line

To use a secret created on the command line, see the example code below. To run the example code:

1. [Create a secret on the command line](#creating-a-secret-on-the-command-line) with the key `my_secret`.
2. Copy the following example code to a new file and save it as `using_secrets.py`.
3. Run the script with `union run --remote using_secrets.py main`.

```python
import union

@union.task(secret_requests=[union.Secret(key="my_secret")])
def t1():
    secret_value = union.current_context().secrets.get(key="my_secret")
    # do something with the secret. For example, communication with an external API.
    ...
```

> [!WARNING]
> Do not return secret values from tasks, as this will expose secrets to the control plane.

With `env_var`, you can automatically load the secret into the environment. This is useful
with libraries that expect the secret to have a specific name:

```python
import union

@union.task(secret_requests=[union.Secret(key="my_union_api_key", env_var="UNION_API_KEY")])
def t1():
    # Authenticates the remote with UNION_API_KEY
    remote = union.UnionRemote(default_project="flytesnacks", default_domain="development")
```

### Using a secret created from a file

To use a secret created from a file in your workflow code, you must mount it as a file. To run the example code below:

1. [Create a secret from a file](#creating-a-secret-from-a-file) with the key `my_secret`.
2. Copy the example code below to a new file and save it as `using_secrets_file.py`.
4. Run the script with `union run --remote using_secrets_file.py main`.

```python
import union

@union.task(
    secret_requests=[
        union.Secret(key="my_file_secret", mount_requirement=union.Secret.MountType.FILE),
    ]
)
def t1():
    path_to_secret_file = union.current_context().secrets.get_secrets_file("my_file_secret")
    with open(path_to_secret_file, "r") as f:
        secret_value = f.read()
    # do something with the secret. For example, communication with an external API.
    ...
```

> [!WARNING]
> Do not return secret values from tasks, as this will expose secrets to the control plane.

> [!NOTE]
> The `get_secrets_file` method takes the secret key and returns the path to the secret file.

## Updating secrets

To update a secret, run the `union update secret` command. You will be prompted to enter a new value:

```shell
$ union update secret --project my_project --domain my_domain my_secret
```

## Deleting secrets

To delete a secret, use the `union delete secret` command:

```shell
$ union delete secret --project my_project --domain my_domain my_secret
```

---
**Source**: https://github.com/unionai/unionai-docs/blob/main/content/user-guide/development-cycle/managing-secrets.md
**HTML**: https://www.union.ai/docs/v1/union/user-guide/development-cycle/managing-secrets/