---
sidebar:
  hidden: true
title: roboto.domain.secrets.secret
---
## Module Contents

### ParsedSecretName

```python
class roboto.domain.secrets.secret.ParsedSecretName
```

`from roboto.domain.secrets.secret import ParsedSecretName`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L30-L32)

**Attributes**

- **ParsedSecretName.name** (`str`)
- **ParsedSecretName.org_id** (`str | None`)

### SECRET_URI_REGEX

```python
roboto.domain.secrets.secret.SECRET_URI_REGEX
```

`from roboto.domain.secrets.secret import SECRET_URI_REGEX`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L26-L26)

### Secret

```python
class roboto.domain.secrets.secret.Secret(
    record: roboto.domain.secrets.record.SecretRecord,
    roboto_client: roboto.http.RobotoClient,
)
```

`from roboto.domain.secrets import Secret`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L48-L462)

A secret stored in the Roboto platform's secret management system.

Secrets provide secure storage for sensitive information like API keys, passwords, and other credentials that can be used by actions during execution. Each secret is scoped to an organization and stored in a secure backend (currently AWS Secrets Manager). The secret's value is never sent through Roboto's APIs, providing an additional layer of security.

Secret names are unique within an organization, so a name + org_id combination provides a fully qualified reference to a specific secret.

Secrets cannot be instantiated directly through the constructor. Use the class methods [`create()`](/reference/python-sdk/roboto/domain/secrets/secret#roboto.domain.secrets.secret.Secret.create), [`from_name()`](/reference/python-sdk/roboto/domain/secrets/secret#roboto.domain.secrets.secret.Secret.from_name), or [`for_org()`](/reference/python-sdk/roboto/domain/secrets/secret#roboto.domain.secrets.secret.Secret.for_org) to create or retrieve secrets.

**Parameters**

- **record** (`roboto.domain.secrets.record.SecretRecord`)
- **roboto_client** (`roboto.http.RobotoClient`)

**Properties**

- **Secret.name** (`str`): Name of the secret.

  Secret names are unique within an organization.

- **Secret.org_id** (`str`): Organization ID that owns this secret.

- **Secret.record** (`roboto.domain.secrets.record.SecretRecord`): The secret record containing metadata and configuration.

- **Secret.store_type** (`roboto.domain.secrets.record.SecretStoreType`): Type of secret store backend where this secret is stored.

  Currently, all secrets are stored in AWS Secrets Manager.

- **Secret.uri** (`str`): URI for this secret.

  This URI can be used to reference the secret in other API calls.

#### Secret.create()

```python
@classmethod
def create(
    name: str,
    caller_org_id: Optional[str] = None,
    initial_value: Optional[str] = None,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> Secret
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L66-L125)

Create a new secret in the Roboto platform.

Creates a new secret with the specified name and optionally sets its initial value. The secret will be stored in the organization's secure secret store (AWS Secrets Manager).

**Parameters**

- **name** (`str`): Name of the secret to create. Must be unique within the organization.
- **caller_org_id** (`Optional[str]`): Organization ID where the secret should be created. If not provided, creates the secret in the caller's organization.
- **initial_value** (`Optional[str]`): Optional initial value to set for the secret. If provided, the secret's value will be set immediately after creation.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If not provided, uses the default client configuration.

**Returns**

- `Secret`: A new Secret instance representing the created secret.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to create secrets in the specified organization.
- [`RobotoConflictException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoConflictException): A secret with the same name already exists in the organization.
- [`RobotoIllegalArgumentException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoIllegalArgumentException): Invalid parameters provided.
- [`RobotoInvalidRequestException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoInvalidRequestException): Malformed request.

**Usage**

Create a secret without an initial value:

```python
secret = Secret.create(name="api_key", caller_org_id="org_123")
print(secret.name)
# 'api_key'
```

Create a secret with an initial value:

```python
secret = Secret.create(
    name="database_password", caller_org_id="org_123", initial_value="super_secure_password"
)
print(secret.name)
# 'database_password'
```

#### Secret.delete()

```python
def delete() -> None
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L336-L356)

Delete this secret from the Roboto platform.

Permanently removes the secret and its value from the secure storage backend. This operation cannot be undone.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to delete this secret.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): The secret no longer exists.

**Returns**

- `None`

**Usage**

Delete a secret:

```python
secret = Secret.from_name("old_api_key")
secret.delete()
# # Secret is now permanently deleted
```

#### Secret.for_org()

```python
@classmethod
def for_org(
    org_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> collections.abc.Generator[Secret, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L128-L185)

Retrieve all secrets belonging to an organization.

Returns a generator that yields all secrets owned by the specified organization. Results are paginated automatically to handle large numbers of secrets efficiently.

**Parameters**

- **org_id** (`str`): Organization ID whose secrets should be retrieved.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If not provided, uses the default client configuration.

**Yields**

- Secret instances for each secret owned by the organization.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to list secrets in the specified organization.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): The specified organization does not exist.

**Returns**

- `collections.abc.Generator[Secret, None, None]`

**Usage**

List all secrets in an organization:

```python
secrets = list(Secret.for_org(org_id="org_123"))
for secret in secrets:
    print(f"Secret: {secret.name}")
# Secret: api_key
# Secret: database_password
```

Process secrets one at a time without loading all into memory:

```python
for secret in Secret.for_org(org_id="org_123"):
    print(f"Processing secret: {secret.name}")
    # Process each secret individually
```

#### Secret.from_name()

```python
@classmethod
def from_name(
    name: str,
    org_id: Optional[str] = None,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> Secret
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L188-L233)

Load an existing secret by name.

Secret names are unique within an organization, so a name + org_id combination provides a fully qualified reference to a specific secret.

**Parameters**

- **name** (`str`): Name of the secret to retrieve. Must be unique within the organization.
- **org_id** (`Optional[str]`): Organization ID that owns the secret. If not provided, searches in the caller's organization.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If not provided, uses the default client configuration.

**Returns**

- `Secret`: A Secret instance representing the found secret.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to access the secret.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): No secret with the specified name exists in the organization.

**Usage**

Load a secret from the caller's organization:

```python
secret = Secret.from_name(name="api_key")
print(secret.name)
# 'api_key'
```

Load a secret from a specific organization:

```python
secret = Secret.from_name(name="database_password", org_id="org_123")
print(f"{secret.name} in {secret.org_id}")
# 'database_password in org_123'
```

#### Secret.from_uri()

```python
@classmethod
def from_uri(
    uri: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
    fallback_org_id: Optional[str] = None,
) -> Secret
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L236-L279)

Load an existing secret by URI.

**Parameters**

- **uri** (`str`): URI of the secret to retrieve.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If not provided, uses the default client configuration.
- **fallback_org_id** (`Optional[str]`): Default organization ID to use if not provided in the URI.

**Returns**

- `Secret`: A Secret instance representing the found secret.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to access the secret.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): No secret with the specified name exists in the organization.
- `ValueError`: The provided URI is not a valid secret URI.

**Usage**

Load a secret from a URI:

```python
secret = Secret.from_uri("roboto-secret://api_key@org_123")
print(f"{secret.name} in {secret.org_id}")
# 'api_key in org_123'
```

Load a secret from a URI with a default org ID:

```python
secret = Secret.from_uri("roboto-secret://api_key", fallback_org_id="org_123")
print(f"{secret.name} in {secret.org_id}")
# 'api_key in org_123'
```

#### Secret.read_value()

```python
def read_value() -> pydantic.SecretStr
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L358-L382)

Read the value stored in this secret.

Securely retrieves the secret's value from the underlying secret store (AWS Secrets Manager). The operation uses temporary, scoped credentials to ensure secure access to the secret store.

**Returns**

- `pydantic.SecretStr`: The secret value as a pydantic.SecretStr.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to read this secret.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): The secret no longer exists.
- `NotImplementedError`: The secret uses an unsupported store type.

**Usage**

Read a secret's value:

```python
secret = Secret.from_name("api_key")
value = secret.read_value()
print(value.get_secret_value())
# 'super_secret_api_key_value'
```

#### Secret.refresh()

```python
def refresh() -> Secret
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L384-L409)

Refresh this secret's metadata from the Roboto platform.

Updates the secret's local metadata by fetching the latest information from the server. This is useful to get updated timestamps or other metadata that may have changed since the secret was last loaded.

**Returns**

- `Secret`: This Secret instance with updated metadata.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to access this secret.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): The secret no longer exists.

**Usage**

Refresh a secret's metadata:

```python
secret = Secret.from_name("api_key")
secret.refresh()
# Secret now has the latest metadata from the server
```

#### Secret.update_value()

```python
def update_value(new_value: str) -> Secret
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L411-L444)

Update the value stored in this secret.

Securely updates the secret's value in the underlying secret store (AWS Secrets Manager). The operation uses temporary, scoped credentials to ensure secure access to the secret store.

**Parameters**

- **new_value** (`str`): The new value to store in the secret.

**Returns**

- `Secret`: This Secret instance for method chaining.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): The caller is not authorized to update this secret.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): The secret no longer exists.
- `NotImplementedError`: The secret uses an unsupported store type.

**Usage**

Update a secret's value:

```python
secret = Secret.from_name("api_key")
secret.update_value("new_secret_api_key_value")
# Secret value has been updated in the secure store
```

Chain method calls:

```python
secret = Secret.create(name="temp_key").update_value("initial_value")
print(secret.name)
# 'temp_key'
```

### is_secret_uri()

```python
def roboto.domain.secrets.secret.is_secret_uri(uri: str) -> bool
```

`from roboto.domain.secrets import is_secret_uri`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L35-L36)

**Parameters**

- **uri** (`str`)

**Returns**

- `bool`

### parse_secret_uri()

```python
def roboto.domain.secrets.secret.parse_secret_uri(uri: str) -> ParsedSecretName
```

`from roboto.domain.secrets.secret import parse_secret_uri`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/secrets/secret.py#L39-L45)

**Parameters**

- **uri** (`str`)

**Returns**

- `ParsedSecretName`