Skip to main content

aip_sdk.secrets

Workspace secrets SDK — store a credential once and give ops access to it by name.

A secret is a named, encrypted value owned by a workspace. An op declares the names it needs and reads them as environment variables while it runs, so a key never has to be written into an op's source, its image, or an evaluation config.

Values are write-only. No listing or lookup returns one; WorkspaceSecret.reveal() is the single call that does, and it needs workspace-admin rights.

aip_sdk.secrets.WorkspaceSecret​

aip_sdk.secrets.WorkspaceSecret(data: dict[str, Any], client: APIClient)

A named, encrypted credential owned by a workspace.

Anyone who can see the workspace can read a secret's name and description; changing or revealing one needs workspace-admin rights. The value is never carried on this object — reveal() fetches it on demand.

Attributes

  • id str: Secret ID.
  • name str: Secret name, unique within its workspace. This is the environment variable an op reads it from.
  • description str | None: What the secret is for, or None.
  • workspace_id str: Workspace that owns the secret.
  • created_at datetime | None: When the secret was created.
  • updated_at datetime | None: When the secret was last changed.

aip_sdk.secrets.WorkspaceSecret.created_at​

aip_sdk.secrets.WorkspaceSecret.created_at: datetime | None = parse_dt(data['created_at'])

No docstring is defined in the source.

aip_sdk.secrets.WorkspaceSecret.delete​

aip_sdk.secrets.WorkspaceSecret.delete() -> None

Delete this secret.

The value is gone afterwards; there is no undo, and a run that expects this name fails to start until a secret with that name exists again.

Raises

aip_sdk.secrets.WorkspaceSecret.description​

aip_sdk.secrets.WorkspaceSecret.description: str | None = data.get('description')

No docstring is defined in the source.

aip_sdk.secrets.WorkspaceSecret.id​

aip_sdk.secrets.WorkspaceSecret.id: str = data['id']

No docstring is defined in the source.

aip_sdk.secrets.WorkspaceSecret.name​

aip_sdk.secrets.WorkspaceSecret.name: str = data['name']

No docstring is defined in the source.

aip_sdk.secrets.WorkspaceSecret.reveal​

aip_sdk.secrets.WorkspaceSecret.reveal() -> str

Return this secret's value.

The only call that returns a stored value, and it needs workspace-admin rights. Ops never use it: an op collects the values a run picked for it on its own, as part of being called. Reach for this to check what was stored against the system that issued it, or to recover a value you hold nowhere else.

Returns

  • str str: the stored value.

Raises

Example:

secret = aip.get_secret("OPENAI_API_KEY", workspace_id="ws-abc123")
client = OpenAI(api_key=secret.reveal())

aip_sdk.secrets.WorkspaceSecret.update​

aip_sdk.secrets.WorkspaceSecret.update(*, name: str | None = None, value: str | None = None, description: str | None = None, clear_description: bool = False) -> WorkspaceSecret

Rename this secret, rotate its value, or change its description.

Only what you pass changes. Passing value replaces the stored credential; the previous one is discarded and the next call an op makes uses the new one, with nothing to publish or restart.

Parameters

  • name str | None: New name, unique within the workspace. Ops reading the old name stop finding it, so rename before an op declares it rather than after.
  • value str | None: New value, encrypted by the platform before storage.
  • description str | None: New description.
  • clear_description bool: Remove the description. Cannot be combined with description.

Returns

Raises

Example:

secret = aip.get_secret("OPENAI_API_KEY", workspace_id="ws-abc123")
secret.update(value=new_key)

aip_sdk.secrets.WorkspaceSecret.updated_at​

aip_sdk.secrets.WorkspaceSecret.updated_at: datetime | None = parse_dt(data['updated_at'])

No docstring is defined in the source.

aip_sdk.secrets.WorkspaceSecret.workspace_id​

aip_sdk.secrets.WorkspaceSecret.workspace_id: str = data['workspace_id']

No docstring is defined in the source.

aip_sdk.secrets.create_secret​

aip_sdk.secrets.create_secret(name: str, value: str, *, description: str | None = None, workspace_id: str | None = None, client: APIClient | None = None) -> WorkspaceSecret

Store a new secret in a workspace.

The name is what an op declares and reads as an environment variable, so it must start with an uppercase letter and hold only uppercase letters, digits and underscores. It must not start with AIP_, or name a variable the op runtime already sets.

Parameters

  • name str: Secret name, unique within the workspace.
  • value str: The value to store. Encrypted by the platform before storage, and never returned by a listing or lookup.
  • description str | None: What the secret is for. Readable by everyone who can see the workspace, so keep the value's own details out of it.
  • workspace_id str | None: Workspace to store it in. Defaults to the session's workspace.
  • client APIClient | None: Optional pre-configured API client.

Returns

Raises

Example:

secret = aip.create_secret(
    "OPENAI_API_KEY",
    os.environ["OPENAI_API_KEY"],
    description="Shared evaluation key",
    workspace_id="ws-abc123",
)

aip_sdk.secrets.get_secret​

aip_sdk.secrets.get_secret(name: str, *, workspace_id: str | None = None, client: APIClient | None = None) -> WorkspaceSecret

Look up one secret by name.

Parameters

  • name str: The secret's name.
  • workspace_id str | None: Workspace holding the secret. Defaults to the session's workspace.
  • client APIClient | None: Optional pre-configured API client.

Returns

  • WorkspaceSecret WorkspaceSecret: the secret, without its value. Call reveal() on it for that.

Raises

Example:

secret = aip.get_secret("OPENAI_API_KEY", workspace_id="ws-abc123")
print(secret.description)

aip_sdk.secrets.list_secrets​

aip_sdk.secrets.list_secrets(*, workspace_id: str | None = None, page: int = 1, per_page: int = 100, client: APIClient | None = None) -> list[WorkspaceSecret]

List a workspace's secrets by name, in alphabetical order.

Open to every member of the workspace: naming a secret is how a run asks for one, and no value is returned here.

Parameters

  • workspace_id str | None: Workspace to read. Defaults to the session's workspace.
  • page int: 1-based page number.
  • per_page int: Page size, between 1 and 100.
  • client APIClient | None: Optional pre-configured API client.

Returns

  • list[WorkspaceSecret]: list[WorkspaceSecret]: the secrets on the requested page, without their values.

Raises

Example:

for secret in aip.list_secrets(workspace_id="ws-abc123"):
    print(secret.name, secret.description)