> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerproduct.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Manage API keys and credentials used by remote functions.

Secrets store API keys, passwords, and cloud credentials. They can supply environment variables to functions and authenticate access to external object stores. Access is controlled through OuterProduct [Policies](https://docs.outerproduct.com/policies.md).

## Creating a Secret

Secrets can be created in the OuterProduct UI or through the Python API. `client.create_secret()` accepts a name and a `SecretValue`, and returns a `Secret` object.

This example stores a Hugging Face token as a generic Secret:

```python theme={null}
import outerproduct as op

client = op.init()

secret: op.Secret = client.create_secret(
    "huggingface-token",
    value=op.SecretValue(generic=b"your-hugging-face-token"),
)
```

Generic values are stored as bytes.

## Secret types

OuterProduct supports several Secret types:

<table>
  <colgroup>
    <col width="127" />

    <col width="595" />
  </colgroup>

  <thead>
    <tr>
      <th>Type</th>
      <th>Supported values</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Generic**</td>
      <td>Arbitrary bytes, such as API tokens and passwords.</td>
    </tr>

    <tr>
      <td>**AWS**</td>
      <td>Access keys, optionally with a session token, or an assume-role configuration referencing another AWS Secret.</td>
    </tr>

    <tr>
      <td>**Google Cloud**</td>
      <td>Service account keys or OAuth access tokens.</td>
    </tr>
  </tbody>
</table>

The type is determined by the `SecretValue` supplied during creation. Cloud credential types provide the information OuterProduct needs to authenticate with the corresponding provider.

## Managing Secrets

`client.list_secrets()` returns accessible Secret metadata without stored values. Use `update_secret()` to replace a value or change its comment. Omitting `value` preserves the current value and version. `delete_secret()` removes the Secret and its stored value.

```python theme={null}
for secret in client.list_secrets():
    print(secret.name)

client.update_secret(
    "huggingface-token",
    value=op.SecretValue(generic=b"replacement-token"),
)
client.delete_secret("old-token")
```

An existing Secret is available through `client.get_secret()`. The returned object contains metadata, including the Secret’s name, type, and version. It acts as a reference when configuring runs and volumes. Calling `get_secret()` does *not* retrieve the stored value:

```python theme={null}
secret: op.Secret = client.get_secret("huggingface-token")
```

If needed for application code, `client.access_secret()` can be used to retrieve the credential directly:

```python theme={null}
response: op.AccessSecretResponse = client.access_secret("huggingface-token")
token: str = response.value.generic.decode("utf-8")
```

Here, `response.value` is the stored `SecretValue`. Its `generic` field contains the token as bytes, and `.decode("utf-8")` converts it to a string. Viewing metadata through `.get_secret()` and accessing values through `.access_secret()` require separate permissions. A user may be allowed to see that a Secret exists without being allowed to retrieve or use its value.

## Using Secrets in environment variables

Generic Secrets containing UTF-8 text can be supplied through `env_vars`:

```python theme={null}
hf_token: op.Secret = client.get_secret("huggingface-token")

run: op.Run[object] | op.Call[object] = client.run(
    fn=download_model,
    image=image,
    env_vars={
        "HF_TOKEN": hf_token,
    },
)
```

OuterProduct resolves the Secret and supplies its value as `HF_TOKEN` in the function’s environment.

## Using Secrets to authorize external volumes

Cloud credential Secrets authenticate access to external object stores. A volume’s provider configuration references the corresponding Secret by name:

```python theme={null}
credential: op.Secret = client.get_secret("aws-storage")

volume_handle: op.VolumeHandle = client.create_volume(
    "external-datasets",
    provider=op.VolumeProvider.S3(
        bucket="my-bucket",
        prefix="datasets/",
        region="us-east-1",
        credential=credential.name,
    ),
)
```

This example assumes `aws-storage` is an AWS Secret. Google Cloud Storage volumes use their corresponding credential types. [Volumes](https://docs.outerproduct.com/volumes.md) includes examples for all three providers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.