# Variables and Secrets Manage reusable values and secure credentials across your custom actions Custom actions require a Pro plan or higher. Upgrade to Pro → ## Application Variables Application variables are reusable values shared across all custom actions in your app. ### Creating Variables 1. Open any custom action 2. Navigate to **Variables** tab 3. Click **Add Variable** | Field | Description | Example | | --------------- | -------------------------------------- | -------------------------------- | | **Name** | Variable identifier (UPPER_SNAKE_CASE) | `API_KEY` | | **Label** | Display name | `API Key` | | **Type** | Data type | `secret` | | **Value** | Actual value | `sk-abc123...` | | **Description** | Usage notes | `OpenAI API key for completions` | ### Variable Types | Type | Use Case | Storage | | ----------- | -------------------- | -------------------------- | | **string** | Text values, URLs | Plain text | | **number** | Numeric values | Plain text | | **boolean** | True/false flags | Plain text | | **secret** | API keys, passwords | Encrypted | | **url** | Base URLs, endpoints | Plain text with validation | ### Using Variables Reference variables with `{{var.VARIABLE_NAME}}` syntax: ```bash https://{{var.API_DOMAIN}}/v{{var.API_VERSION}}/endpoint Authorization: Bearer {{var.API_KEY}} X-Workspace-ID: {{var.WORKSPACE_ID}} { "api_key": "{{var.API_KEY}}", "environment": "{{var.ENVIRONMENT}}" } ``` ### Variable Resolution Variables can be used in: - **Exact match**: Entire value is the variable - **Embedded**: Variable within a larger string ```bash {{var.API_KEY}} Bearer {{var.API_KEY}} https://{{var.DOMAIN}}/api/v{{var.VERSION}} ``` ## System Variables Built-in variables provided by the platform at runtime. ### Available System Variables | Variable | Description | Type | Example | | ---------------------------- | ------------------------- | ------ | ---------------------- | | `{{system.message_history}}` | Full conversation history | Array | OpenAI messages format | | `{{system.user_id}}` | Current user's unique ID | String | `user_abc123` | | `{{system.timestamp}}` | Unix timestamp (seconds) | String | `1713552052` | ### Message History Format The `message_history` variable returns OpenAI-formatted messages: ```json [ { "role": "user", "content": "What's the weather in NYC?" }, { "role": "assistant", "content": "I'll check the weather for you." } ] ``` ### Using System Variables ```json { "messages": {{system.message_history}}, "metadata": { "user": "{{system.user_id}}", "timestamp": "{{system.timestamp}}", "source": "custom_action" } } ``` ## Security Best Practices ### 1. Use Secret Type for Sensitive Data Mark sensitive values as `secret`: ```bash Type: secret Name: API_KEY Value: sk-abc123... Type: string Name: API_KEY Value: sk-abc123... ``` ### 2. Never Expose Secrets in URLs ```bash https://api.example.com/auth?key={{var.API_KEY}} Headers: Authorization: Bearer {{var.API_KEY}} ``` ### 3. Scope Variables Appropriately Variables are scoped to applications, not global: - Each app has its own variable namespace - No cross-app variable access - User-specific isolation ### 4. Rotate Keys Regularly Update variable values without changing actions: 1. Go to Variables tab 2. Update the value 3. All actions automatically use new value ## Common Patterns ### Environment Configuration Manage different environments with variables: ```bash API_DOMAIN = api.dev.example.com ENVIRONMENT = development API_DOMAIN = api.example.com ENVIRONMENT = production ``` ### Multi-Tenant Setup Use variables for tenant-specific values: ```bash WORKSPACE_ID = ws_123456 TENANT_KEY = tenant_abc ORG_ID = org_789 ``` ### API Versioning Control API versions centrally: ```bash API_VERSION = v2 SCHEMA_VERSION = 2024-01-15 CLIENT_VERSION = 1.2.3 ``` ## Variable Management ### Viewing Variable Usage See which actions use a variable: - Green dot indicates usage in current action - Check before deleting variables - Update impacts all actions ### Import/Export When exporting actions to collections: - Variable definitions included - Variable values NOT exported - Recipients set their own values ### Testing Variables Use the action tester to verify resolution: ```bash URL: {{var.BASE_URL}}/users Header: Bearer {{var.API_KEY}} URL: https://api.example.com/users Header: Bearer sk-abc123... ``` ## AI Placeholders Simple placeholders without namespace become AI-generated: ```bash {{userId}} # AI determines user ID {{searchQuery}} # AI creates search term {{emailSubject}} # AI writes subject {{var.API_KEY}} # Application variable {{system.user_id}} # System variable ``` ## Troubleshooting ### Variables Not Resolving 1. **Check Variable Name** - Case-sensitive - No spaces in names - Correct namespace (`var.` or `system.`) 2. **Check Variable Definition** - Variable exists in Variables tab - Has a value set - Correct variable type 3. **Check Syntax** - Double curly braces: `{{}}` - No extra spaces: `{{var.NAME}}` - Correct namespace prefix ### Secret Values Not Visible Secrets are encrypted and never shown after saving: - ✓ This is expected behavior - ✓ Update value to change - ✓ Use tester to verify working ### Cross-Action Dependencies Variables are resolved per action: - Define once, use everywhere - Changes apply immediately - No action rebuild required ## Next Steps - [Test Your Actions →](/docs/custom-actions/testing) - [View Examples →](/docs/custom-actions/examples) - [Parameter Configuration →](/docs/custom-actions/parameters)