Storage connections

client.storage_connections manages the storage connections a new workspace can keep its files in, instead of Nace's managed storage. See Use your own storage for the concept, and the API reference for every field.

• A connection names one destination: an S3 bucket and region, or an Azure storage account and container, with an optional base prefix. Each workspace gets its own folder beneath it. The destination can't change.
• Who can do what: any member of the account lists and reads connections and binds a ready one to a new workspace. Only a connection's creator, or an owner or admin of the account, changes it; anyone else raises NacePermissionDeniedError (access_denied).
• Cost: managing connections costs nothing and works at any balance.
• Availability: a deployment that doesn't offer customer storage raises NaceNotFoundError (storage_connection_unavailable) on every call.

A connection's status is one of:

A connection is set up in five steps:

1. create makes a draft.
2. setup returns what to create in your cloud: for S3, an IAM role trust policy carrying the connection's external_id, its permissions policy, a CloudFormation template and a quick-create link; for Azure, the az commands that give a service principal access to the container. Save your AWS account id and role name, or your Azure subscription and resource group, with set_setup first, and the setup comes back filled in.
3. Create the role or service principal in your cloud.
4. set_credentials saves the role's ARN, or the service principal and its secret.
5. validate starts a storage_validation job, and wait_for_validation waits for it. Once it succeeds, the connection is ready.

A new IAM role or Azure role assignment can take a few minutes to apply, so a fresh one may fail its first validation: wait and validate again. Then pass the connection's id as storage_connection_id to client.workspaces.create. Only a connection whose is_ready is True can be bound: status is ready, and credentials_pending, validation_running and reactivation_requires_approval are all False.

• The Azure secret is a SecretStr on AzureServicePrincipalCredential: its repr, str() and model_dump_json() show **********, a validation error never quotes it, and SDK debug logs mask client_secret in request bodies. Only the request to Drex carries it. A dict credential works too, with the secret as a str or a SecretStr.
• Retries: list, iter, get, setup, set_setup, set_credentials, validation and revoke are retried, and so is create, which carries an idempotency key. validate and delete aren't, unless you pass retry: a retry after the first call landed starts a second validation, or raises NaceNotFoundError for the deleted connection.

List connectionsCopy Anchor Link

from nace_sdk import NaceClient

with NaceClient() as client:
    page = client.storage_connections.list(limit=20)
    for connection in page.items:
        print(connection.id, connection.name, connection.status)

    for connection in client.storage_connections.iter():
        print(connection.id, connection.destination.type, connection.is_ready)

Connect an S3 bucketCopy Anchor Link

from nace_sdk import AwsRoleCredential, S3Destination, S3SetupOptions

connection = client.storage_connections.create(
    name="Audit evidence bucket",
    destination=S3Destination(bucket="acme-audit-evidence", region="us-east-1", prefix="nace"),
)
setup = client.storage_connections.set_setup(
    connection.id, S3SetupOptions(aws_account_id="444455556666", role_name="nace-workspaces")
)
print(setup.launch_url)  # opens the CloudFormation stack that creates the role

# Once the stack has created the role:
client.storage_connections.set_credentials(connection.id, AwsRoleCredential(role_arn=setup.role_arn))
client.storage_connections.validate(connection.id)
job = client.storage_connections.wait_for_validation(connection.id)
print(job.status, job.error_message)

Connect an Azure Blob containerCopy Anchor Link

import os

from nace_sdk import AzureBlobDestination, AzureServicePrincipalCredential, AzureSetupOptions

connection = client.storage_connections.create(
    name="Audit evidence container",
    destination=AzureBlobDestination(account="acmeaudit", container="evidence"),
)
setup = client.storage_connections.set_setup(
    connection.id, AzureSetupOptions(subscription_id="<subscription id>", resource_group="audit-rg")
)
print(setup.azure_cli)  # run these to give your service principal access

client.storage_connections.set_credentials(
    connection.id,
    AzureServicePrincipalCredential(
        tenant_id="<tenant id>", client_id="<client id>", client_secret=os.environ["AZURE_CLIENT_SECRET"]
    ),
)
client.storage_connections.validate(connection.id)
print(client.storage_connections.wait_for_validation(connection.id).status)

Create a workspace in your storageCopy Anchor Link

Pass a ready connection's id as storage_connection_id. See Create a workspace.

connection = client.storage_connections.get(connection.id)
if connection.is_ready:
    workspace = client.workspaces.create(name="fy25-audit", storage_connection_id=connection.id)
    print(workspace.storage.location)