Secrets

API keys and other credentials are stored on the tenant, by name. Agent setups, LLM configurations and tracing configurations refer to them by that name.

Tenant secrets

Every tenant has a list of named secrets. In the Platform Admin, open a tenant and go to Secrets: each entry has a name and a value, and shows which configurations use it. The value is encrypted at rest; the API returns it only as ciphertext.

Referencing a secret

Credential fields end in _ref and take the secret's name:

"vendor_configuration": {
  "openai": {
    "openai_api_key_ref": "openai-api-key"
  }
}

In the Platform Admin, the LLM Configurations section lets you pick a stored secret from a list, or type a new value and store it under a suggested name in one step.

Custom dependencies

A dependency of your own that needs a credential declares an EncryptedStrRef field on its configuration model and reads the value in create():

from zav.encryption.pydantic import EncryptedStrRef


class HubspotConfiguration(BaseModel):
    api_key_ref: EncryptedStrRef


class HubspotClientFactory(AgentDependencyFactory):
    @classmethod
    def create(cls, hubspot_configuration: HubspotConfiguration) -> HubspotClient:
        return HubspotClient(api_key=hubspot_configuration.api_key_ref.get_unencrypted_secret())

The agent setup names the secret:

"agent_configuration": {
  "hubspot_configuration": { "api_key_ref": "hubspot-api-key" }
}

The SDK resolves the reference when it builds the dependency. A reference is honoured only when the agent setup itself contains it; a request cannot add one.

Local projects

A za agents project keeps the same shape on disk:

file	holds
env/secrets.json	[{"name": ..., "value": ...}], the credentials that become the tenant's secrets when you deploy
env/zav_config.json	your platform logins, one per tenant, from za platform login; when the project runs each agent gets the login of its tenant (else the current one) as x_auth, never part of a setup

The CLI maintains env/secrets.json. za agents init, model add, model configure and agent add ask for the credential, store it under <configuration>-<field> and write the reference into llm_configurations.json. Typing the name of an existing secret references it; typing a new value for a field that already has a reference rotates that secret. za agents deploy bundle validates the project first and reports references that do not resolve.

When you deploy, create the same secrets on the tenant with the same names. The configurations carry over unchanged.

Projects created before secrets existed keep working. Run za agents model configure and re-enter the credential to move a configuration onto a secret.