Overview
Workflows often need to communicate with external systems, such as third-party APIs, webhooks, or internal services, to fetch data, verify records, or post updates. Authenticating with these services requires sensitive credentials such as API keys, bearer tokens, and signing secrets.
Platform Secrets provide a secure, centralized way to store sensitive credentials at the organization level and reference them dynamically within your Workflows. Instead of hardcoding credentials in step configurations, you define a secret key once and resolve its environment-specific value at runtime.
Why use Platform Secrets?
Managing credentials directly inside Workflow steps introduces operational risks. Platform Secrets solve these challenges through several key architectural benefits:
- Enhanced security: Keep sensitive credentials out of plain-text step configurations and Workflow JSON definitions. Builders can configure and maintain Workflows without needing direct access to production secrets.
- Environment isolation: Assign distinct secret values for Sandbox and Production environments under the exact same secret name. When you promote a Workflow from Sandbox to Production, the Workflow references the same secret path (such as
current_run.environment.secrets.crm_api_key) while automatically resolving the appropriate credentials for each environment. - Centralized key rotation: When an external credential expires or must be rotated, update the secret once in the Persona Dashboard. Every Workflow that references the secret immediately uses the new value without requiring edits, re-testing, or new published versions.
- Preventing credential leaks: By isolating secrets behind dedicated role-based permissions, you prevent unauthorized team members from viewing or copying sensitive keys.
Managing Platform Secrets in the Dashboard
Users with appropriate permissions can view, create, and manage secrets directly in the Persona Dashboard.
Creating a secret
- In the Persona Dashboard, navigate to Utilities > Secrets.
- Click + Add secret to open the secret creation modal.
- Configure the secret details:
- Secret key: Enter a unique alphanumeric identifier using snake_case (for example,
slack_webhook_urlorcrm_api_key). This is the key name referenced in Workflows. - Description: Add context explaining what service or API uses this secret.
- Sandbox value: Provide the secret value to use when Workflows run in Sandbox.
- Production value: Provide the secret value to use when Workflows run in Production.
- Secret key: Enter a unique alphanumeric identifier using snake_case (for example,
- Click Save secret.
Secret key names cannot be renamed after creation to prevent breaking published Workflows that reference them. If you need a different key name, create a new secret and update your Workflow steps.
Rotating or updating a secret value
When rotating a credential:
- Navigate to Utilities > Secrets.
- Select the secret you want to update from the list.
- Enter the new value for Sandbox, Production, or both.
- Click Save. The updated values take effect immediately on subsequent Workflow executions.
Referencing secrets in Workflows
In the Workflow editor, you can reference Platform Secrets in action steps that support dynamic method chains, variable interpolation, or template syntax.
Secret resolution path
Platform Secrets are accessed via the current_run.environment.secrets method chain:
current_run.environment.secrets.<secret_name>For example, if you created a secret named kyc_partner_token, reference it as:
current_run.environment.secrets.kyc_partner_tokenCommon use cases
Platform Secrets are commonly referenced in:
- Make HTTPS Request steps: Add authorization headers such as
Bearer {{current_run.environment.secrets.api_key}}or custom API key headers (such asX-API-Key: {{current_run.environment.secrets.vendor_key}}) without exposing credentials in the step configuration. - Webhook and notification steps: Securely supply shared HMAC signing secrets or endpoint authorization tokens.
- Compute and calculation steps: Pass secret values into dynamic expressions or method chains that format payloads for external downstream systems.
Platform Secrets use lazy resolution. Secrets are fetched and decrypted one key at a time only when the step referencing them executes, minimizing unnecessary credential access.
Security and execution log redaction
Persona enforces strict safeguards to protect secrets throughout the Workflow execution lifecycle:
- Automatic log redaction: When a Workflow runs, any value resolved from
current_run.environment.secretsis automatically masked and redacted in Workflow execution logs, run history details, and step audit outputs (rendered as[REDACTED]). - Data storage isolation: Secret values are encrypted at rest using envelope encryption and are never stored in plain text in database records or run state snapshots.
- Access restriction: Workflow run viewers cannot inspect decrypted secret values in the execution graph, even if they have permission to inspect step inputs and outputs.
Never output secret values directly into end-user visible channels (such as SMS bodies, customer-facing emails, or plain-text Inquiry notes), as redaction only applies to Persona execution logs and step inspection panels.
Required permissions
Access to Platform Secrets is governed by role-based access control (RBAC). The following permissions control access to secrets:
| Permission | Description |
|---|---|
organization-secret.view | Allows users to view the list of Platform Secrets, secret keys, descriptions, and metadata in the Dashboard. Decrypted secret values remain hidden. |
organization-secret.write | Allows users to create new secrets, update existing secret values, rotate keys, and delete secrets. |
Organizations can attach these permissions to custom roles or assign them to Administrators and Lead Builders who manage integration infrastructure.