roboto.domain.secrets#

Submodules#

Package Contents#

class roboto.domain.secrets.AwsSecretRetrievalLocation(/, **data)#

Bases: pydantic.BaseModel

Information required to retrieve a secret from AWS Secrets Manager.

Parameters:

data (Any)

arn: str#

ARN of the secret.

store_type: Literal[SecretStoreType]#

Type of secret store. Referenced here explicitly to make deserialization work better.

class roboto.domain.secrets.AwsSecretsManagerAccessCreds(/, **data)#

Bases: pydantic.BaseModel

Context required to update a secret in AWS Secrets Manager.

Parameters:

data (Any)

access_key_id: str#

AWS access key ID.

region: str#

AWS region.

secret_access_key: str#

AWS secret access key.

session_token: str#

AWS session token.

store_type: Literal[SecretStoreType]#

Type of secret store. Referenced here explicitly to make deserialization work better.

class roboto.domain.secrets.CreateSecretRequest(/, **data)#

Bases: pydantic.BaseModel

Request payload for the Create Secret

Parameters:

data (Any)

name: str#

Name of the secret.

class roboto.domain.secrets.GetSecretAccessCredsResponse(/, **data)#

Bases: pydantic.BaseModel

Response payload for the Update Secret

Parameters:

data (Any)

creds: SecretAccessCreds = None#

Creds required to update the secret in its underlying data store.

record: SecretRecord#

The secret whose value is going to be updated.

class roboto.domain.secrets.Secret(record, roboto_client)#

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(), from_name(), or for_org() to create or retrieve secrets.

Parameters:
classmethod create(name, caller_org_id=None, initial_value=None, roboto_client=None)#

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:

A new Secret instance representing the created secret.

Raises:
Return type:

Secret

Examples

Create a secret without an initial value:

>>> secret = Secret.create(name="api_key", caller_org_id="org_123")
>>> print(secret.name)
'api_key'

Create a secret with an initial value:

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

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:
Return type:

None

Examples

Delete a secret:

>>> secret = Secret.from_name("old_api_key")
>>> secret.delete()
# Secret is now permanently deleted
classmethod for_org(org_id, roboto_client=None)#

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:
Return type:

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

Examples

List all secrets in an organization:

>>> 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:

>>> for secret in Secret.for_org(org_id="org_123"):
...     print(f"Processing secret: {secret.name}")
...     # Process each secret individually
classmethod from_name(name, org_id=None, roboto_client=None)#

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:

A Secret instance representing the found secret.

Raises:
Return type:

Secret

Examples

Load a secret from the caller’s organization:

>>> secret = Secret.from_name(name="api_key")
>>> print(secret.name)
'api_key'

Load a secret from a specific organization:

>>> secret = Secret.from_name(name="database_password", org_id="org_123")
>>> print(f"{secret.name} in {secret.org_id}")
'database_password in org_123'
classmethod from_uri(uri, roboto_client=None, fallback_org_id=None)#

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:

A Secret instance representing the found secret.

Raises:
Return type:

Secret

Examples

Load a secret from a URI:

>>> 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:

>>> 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'
property name: str#

Name of the secret.

Secret names are unique within an organization.

Return type:

str

property org_id: str#

Organization ID that owns this secret.

Return type:

str

read_value()#

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:

The secret value as a pydantic.SecretStr.

Raises:
Return type:

pydantic.SecretStr

Examples

Read a secret’s value:

>>> secret = Secret.from_name("api_key")
>>> value = secret.read_value()
>>> print(value.get_secret_value())
'super_secret_api_key_value'
property record: roboto.domain.secrets.record.SecretRecord#

The secret record containing metadata and configuration.

Return type:

roboto.domain.secrets.record.SecretRecord

refresh()#

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:

This Secret instance with updated metadata.

Raises:
Return type:

Secret

Examples

Refresh a secret’s metadata:

>>> secret = Secret.from_name("api_key")
>>> secret.refresh()
>>> # Secret now has the latest metadata from the server
property 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.

Return type:

roboto.domain.secrets.record.SecretStoreType

update_value(new_value)#

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:

This Secret instance for method chaining.

Raises:
Return type:

Secret

Examples

Update a secret’s value:

>>> 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:

>>> secret = Secret.create(name="temp_key").update_value("initial_value")
>>> print(secret.name)
'temp_key'
property uri: str#

URI for this secret.

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

Return type:

str

roboto.domain.secrets.SecretAccessCreds#

Union type for all possible secret update contexts.

class roboto.domain.secrets.SecretRecord(/, **data)#

Bases: pydantic.BaseModel

A wire-transmissible representation of a secret.

Parameters:

data (Any)

created: datetime.datetime#

Timestamp when the secret was created.

created_by: str#

RobotoPrincipal which created the secret.

last_used: datetime.datetime | None = None#

Timestamp when the secret was last used in an action, or None if the secret has never been used.

location: SecretRetrievalLocation = None#

Information required to dereference the secret in its specific secret store. This is used in combination with temporary hyper-downscoped access creds to update or retrieve the secret’s value.

modified: datetime.datetime#

Timestamp when the secret was last modified.

modified_by: str#

RobotoPrincipal which last modified the secret.

name: str#

Name of the secret. Secret names must be unique within an organization.

org_id: str#

Organization ID that owns the secret.

store_type: SecretStoreType#

Type of secret store.

class roboto.domain.secrets.SecretStoreType#

Bases: str, enum.Enum

Type of secret store.

AWS = 'aws'#

AWS Secrets Manager.

roboto.domain.secrets.is_secret_uri(uri)#
Parameters:

uri (str)

Return type:

bool

On this page