# AsyncSecret

## Secret

```python
class Secret(SecretDto)
```

Represents an organization-scoped Daytona Secret.

The plaintext ``value`` is write-only and is never returned by the API. When a Secret is
referenced from a Sandbox, the injected environment variable holds the opaque ``placeholder``
token, not the real value. The real value is substituted transparently on outbound requests
to the Secret's allowed ``hosts``.

**Attributes**:

- `id` _str_ - Unique identifier for the Secret.
- `name` _str_ - Name of the Secret (unique within the organization).
- `description` _str | None_ - Optional description of the Secret.
- `placeholder` _str_ - Opaque token injected as the env var value in Sandboxes.
- `hosts` _list[str]_ - Hosts the Secret value may be sent to (may be empty).
- `created_at` _datetime_ - Date and time when the Secret was created.
- `updated_at` _datetime_ - Date and time when the Secret was last updated.


## AsyncSecretService

```python
class AsyncSecretService()
```

Service for managing organization-scoped Daytona Secrets.

Can be used to create, list, get, update and delete Secrets. Secrets can be mounted into
Sandboxes as environment variables by referencing them via the ``secrets`` field on the
create-sandbox parameters. The Sandbox only ever sees the Secret's opaque placeholder; the
real value is substituted at the network egress layer for the Secret's allowed hosts.

#### AsyncSecretService.list

```python
async def list() -> list[Secret]
```

List all Secrets in the organization.

**Returns**:

- `list[Secret]` - List of all Secrets in the organization.
  

**Example**:

```python
async with AsyncDaytona() as daytona:
    secrets = await daytona.secret.list()
    for secret in secrets:
        print(f"{secret.name} ({secret.id})")
```

#### AsyncSecretService.get

```python
@with_instrumentation()
async def get(secret_id: str) -> Secret
```

Get a Secret by its ID.

**Arguments**:

- `secret_id` _str_ - ID of the Secret to retrieve.
  

**Returns**:

- `Secret` - The requested Secret.
  

**Raises**:

- `NotFoundException` - If the Secret does not exist.
  

**Example**:

```python
async with AsyncDaytona() as daytona:
    secret = await daytona.secret.get("secret-id")
    print(f"{secret.name} can be used on {', '.join(secret.hosts)}")
```

#### AsyncSecretService.create

```python
@with_instrumentation()
async def create(params: CreateSecretParams) -> Secret
```

Create a new Secret.

**Arguments**:

- `params` _CreateSecretParams_ - Parameters for the new Secret.
  

**Returns**:

- `Secret` - The newly created Secret (without the plaintext ``value``).
  

**Raises**:

- `ApiException` - If a Secret with the same name already exists in the organization (409).
  

**Example**:

```python
async with AsyncDaytona() as daytona:
    secret = await daytona.secret.create(
        CreateSecretParams(
            name="anthropic-prod",
            value="sk-ant-...",
            hosts=["api.anthropic.com"],
        )
    )
    print(f"Created secret {secret.name} with placeholder {secret.placeholder}")
```

#### AsyncSecretService.update

```python
@with_instrumentation()
async def update(secret_id: str, params: UpdateSecretParams) -> Secret
```

Update an existing Secret. Omitted fields are left unchanged.

**Arguments**:

- `secret_id` _str_ - ID of the Secret to update.
- `params` _UpdateSecretParams_ - Fields to update.
  

**Returns**:

- `Secret` - The updated Secret.
  

**Raises**:

- `NotFoundException` - If the Secret does not exist.
  

**Example**:

```python
async with AsyncDaytona() as daytona:
    secret = await daytona.secret.update(
        "secret-id",
        UpdateSecretParams(
            value="sk-ant-new-value",
            hosts=["api.anthropic.com", "*.anthropic.com"],
        ),
    )
```

#### AsyncSecretService.delete

```python
@with_instrumentation()
async def delete(secret_id: str) -> None
```

Delete a Secret.

**Arguments**:

- `secret_id` _str_ - ID of the Secret to delete.
  

**Raises**:

- `NotFoundException` - If the Secret does not exist.
  

**Example**:

```python
async with AsyncDaytona() as daytona:
    await daytona.secret.delete("secret-id")
    print("Secret deleted")
```

## CreateSecretParams

```python
class CreateSecretParams(BaseModel)
```

Parameters for creating a new Secret.

**Attributes**:

- `name` _str_ - Name of the Secret. Must match ``^[a-zA-Z_][a-zA-Z0-9_-]*$`` and be unique
  within the organization.
- `value` _str_ - The plaintext Secret value. Stored encrypted and never returned by the API.
- `description` _str | None_ - Optional description of the Secret.
- `hosts` _list[str] | None_ - Hosts the Secret value may be sent to. Each entry is a hostname
  (``api.example.com``) or a ``*.`` wildcard (``*.example.com``); ports are not supported.
  Omit to leave the Secret unrestricted.

## UpdateSecretParams

```python
class UpdateSecretParams(BaseModel)
```

Parameters for updating an existing Secret. Omitted fields are left unchanged.

**Attributes**:

- `value` _str | None_ - Replaces the stored Secret value when present.
- `description` _str | None_ - Optional description of the Secret.
- `hosts` _list[str] | None_ - Hosts the Secret value may be sent to. Same constraints as
  :class:`CreateSecretParams.hosts`.