Using the Credential Store in Syntasa Notebooks

Syntasa Notebooks integrate seamlessly with the Credential Store, enabling you to securely access sensitive information—such as API tokens, database passwords, and service keys—directly within your code. By leveraging the syn_utils library, you can retrieve secrets programmatically without hardcoding them into notebook cells, ensuring your notebooks remain secure, reusable, and easy to share.

The syn_utils SDK

The primary interface for working with credentials in a notebook is the CredentialStore class, available in the syn_utils library.

This SDK automatically handles:

  • Authentication
  • Communication with the Syntasa API

This allows you to focus on using credentials rather than managing access or security logic.

Security Features: Masking

To prevent accidental exposure of sensitive data in notebook outputs or logs, the SDK provides two protective wrappers:

  • SecretString: Wraps a single secret value
  • SecretDict: Wraps a collection (dictionary) of secret values

When printed or displayed, these objects appear as: **********

To access the actual underlying value, you must explicitly call the .get() method.

Getting Started

Initialize the Credential Store

Start by importing the class and creating an instance:

from syn_utils import CredentialStore
# Initialize the store
store = CredentialStore()

The SDK automatically retrieves required environment variables (SYNTASA_AUTH_TOKEN and SYNTASA_APP_URL) from the notebook environment.

List Available Credentials

To view credentials you have access to (owned, public, or shared with your groups), use the list() method.

# List all accessible credentials
credentials_list = store.list()

for cred in credentials_list:
    print(f"Name: {cred['name']}, Source: {cred['sourceType']}")

Note: This method returns only metadata—it does not retrieve any secret values.

Retrieve a Secret Value

To retrieve a specific value from a credential, use the get() method with:

  • Credential Name
  • Key within the credential
# Retrieve a specific key
# Returns a SecretString object
api_token = store.get("My_API_Credential", "token")

# Printing the object shows masked output
print(api_token)  # Output: **********

# Use .get() to pass the actual value to a function
# response = requests.get(url, headers={"Authorization": f"Bearer {api_token.get()}"})

Retrieve All Keys in a Credential

If a credential contains multiple keys (e.g., username and password), use get_all():

# Returns a SecretDict
secrets = store.get_all("Database_Credentials")

# Access individual keys from the SecretDict
db_user = secrets["username"]
db_pass = secrets["password"]

print(f"Connecting as: {db_user.get()}")

Each value is still wrapped and requires .get() to access the raw secret.

Advanced Metadata Operations

If you need to inspect credential configuration without retrieving secret values, use:

  • get_metadata(name): Returns basic metadata
  • describe(name): Returns detailed information including description, owner, and last modified timestamp
# Get detailed information
info = store.describe("My_API_Credential")
print(info)

Error Handling

The SDK raises specific errors to help identify issues:

  • Access Denied
    • Occurs when attempting to access a credential not shared with you
  • Key Not Found
    • Occurs when the credential exists but the requested key does not
  • RuntimeError
    • Occurs when a cloud-referenced credential (AWS/GCP/Azure) cannot fetch its value
    • Example: expired or insufficient platform permissions

Best Practices

Avoid Printing Raw Secrets

Never call .get() inside a print statement. Only use it when passing values to external libraries or functions.

Use Cloud References for Rotation

If your organization rotates secrets in cloud providers like AWS Secrets Manager or GCP Secret Manager, use the Cloud Secret Reference type.
The CredentialStore always retrieves the latest (or specified) version, ensuring your notebook uses up-to-date values.

Verify Permissions

If a notebook cannot fetch a cloud secret:

  • Check that the Syntasa platform IAM role has the correct permissions
    • Example: GetSecretValue or secretAccessor

By using the Credential Store within Syntasa Notebooks, you ensure that sensitive information is handled securely while maintaining clean, reusable, and production-ready code.