> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Credentials
> Securely store and manage sensitive API keys, tokens, and secrets for use in your workflows
## What are Credentials?
Credentials are encrypted key-value pairs that allow you to securely store sensitive information like API keys, tokens, and secrets. Instead of hardcoding sensitive values in your workflow code, you can reference them by name and the system will securely inject them at runtime.
### Why Use Credentials?
| Without Credentials | With Credentials |
| ------------------------------------- | ------------------------------------------- |
| API keys hardcoded in code | Values stored encrypted, referenced by name |
| Risk of accidentally exposing secrets | Secrets never visible in logs or UI |
| Difficult to rotate keys | Easy rotation without changing code |
| Same key repeated across workflows | Single source of truth for all workflows |
## Managing Credentials
### Accessing Credentials Settings
Navigate to **Workspace Settings** → **Credentials** to manage your workspace credentials.
### Creating a Credential
1. Click **Add Credential**
2. Enter a **Key** (identifier you'll use in code, e.g., `SLACK_BOT_TOKEN`)
3. Enter the **Value** (the actual secret)
4. Click **Save**
The credential value is encrypted before storage. Once saved, you cannot view the value again — you can only update or delete it.
### Credential Key Naming
Choose descriptive, consistent names for your credential keys:
```
SLACK_BOT_TOKEN
OPENAI_API_KEY
DATABASE_PASSWORD
GITHUB_ACCESS_TOKEN
STRIPE_SECRET_KEY
```
Use uppercase with underscores for consistency, similar to environment variables. This makes it easy to identify credentials in your code.
### Updating a Credential (Rotation)
To rotate a credential:
1. Find the credential in the list
2. Click **Edit**
3. Enter the new value
4. Click **Save**
The new value takes effect immediately for any new workflow executions.
### Deleting a Credential
Deleting a credential will cause any workflow referencing it to fail with a `missing_credential` error. Make sure no active workflows depend on the credential before deleting.
## Using Credentials in Code Execution
In **Code Execution** steps, use the `credential()` function to retrieve secret values at runtime.
### JavaScript/TypeScript
```javascript theme={null}
// Get a credential value
const apiKey = credential("OPENAI_API_KEY");
// Use it in your code
const response = await fetch("https://api.openai.com/v1/chat/completions", {
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
// ...
});
```
## Using Credentials in Agents
When a workflow executes an **Agent step**, all workspace credentials are automatically available to the agent. You can instruct the agent to use a specific credential by referencing its name in your prompt or agent configuration.
For example, you can tell the agent: *"Use the SLACK\_BOT\_TOKEN credential to send a message to the #general channel."*
Credentials are inherited from the workflow's scope. The agent receives the same credentials available to the workflow that triggered it.
## How Credentials Work at Runtime
When a workflow step executes:
1. The system resolves all available credentials for the workspace
2. Credentials are decrypted and injected into the step's runtime environment
3. The `credential()` function reads from this secure context
4. Credential values are kept in memory only — never persisted in logs, outputs, or state
The system uses best-effort masking to prevent credential values from appearing in logs. However, if your code explicitly prints a credential value, it may still be visible.
## Credential Scopes
Credentials can be defined at two levels:
* **Workspace level**: Available to all workflows in the workspace (default)
* **Workflow level**: Specific to a single workflow, overriding workspace credentials with the same key
### Workspace Credentials
Workspace credentials are the default scope. They're available to all workflows and serve as the fallback when no workflow-scoped credential exists.
### Workflow-Scoped Credentials
You can create credentials that are specific to a single workflow. This is useful when:
* A workflow needs a different API key than the workspace default
* You want to isolate credentials for security purposes
* Different workflows connect to different environments (staging vs production)
To manage workflow-scoped credentials:
1. Open the workflow you want to configure
2. Click the **Credentials** button in the workflow header
3. Add credentials specific to this workflow
Workflow-scoped credentials with the same key as workspace credentials will **override** the workspace value for that specific workflow only.
## Credentials Allowlist
For additional security control, you can define an **allowlist** of credentials for each workflow. When an allowlist is configured, only the specified credentials are accessible during workflow execution.
### Why Use an Allowlist?
| Scenario | Benefit |
| ---------------------------- | ------------------------------------------------------- |
| Principle of least privilege | Workflows only access credentials they need |
| Multi-tenant workflows | Prevent accidental access to other clients' keys |
| Security audits | Clear documentation of which secrets each workflow uses |
| Onboarding new team members | Reduced risk from misconfigured workflows |
### Configuring the Allowlist
1. Open the workflow you want to configure
2. Click the **Credentials** button in the workflow header
3. Go to the **Usage Permissions** tab
4. Toggle on the credentials this workflow should have access to
If no allowlist is defined, the workflow has access to all workspace credentials (backwards compatible behavior).
When using an allowlist, make sure to include all credentials your workflow needs. Missing credentials will cause the workflow to fail at runtime.
## Security Considerations
### Encryption
All credential values are encrypted using **AES-256-GCM** before storage. Values are only decrypted at the moment of execution and kept in memory for the minimum time necessary.
### Access Control
* Only **workspace administrators** can create, update, or delete credentials
* Users with workflow edit/execute permissions can **reference** credentials by key, but cannot view values
## Error Handling
### Missing Credential
If your code references a credential that doesn't exist:
```javascript theme={null}
// This will throw an error if MY_KEY doesn't exist
const value = credential("MY_KEY");
// Error: missing_credential - Credential 'MY_KEY' not found
```
**Solution:** Create the credential in Workspace Settings before running the workflow.
### Best Practice: Validate Early
Check for required credentials at the start of your code:
```javascript theme={null}
// Validate all required credentials upfront
const slackToken = credential("SLACK_BOT_TOKEN");
const openaiKey = credential("OPENAI_API_KEY");
if (!slackToken || !openaiKey) {
throw new Error("Missing required credentials");
}
// Continue with your logic...
```
## Best Practices
* Use descriptive, consistent key names
* Rotate credentials periodically
* Use separate credentials for different services
* Test workflows after credential rotation
* Document what each credential is used for
* Hardcode secrets in workflow code
* Log or print credential values
* Share credential values outside the system
* Use the same credential for multiple purposes
* Delete credentials without checking dependencies
## Frequently Asked Questions
No. For security reasons, credential values cannot be retrieved after creation. You can only update (overwrite) or delete them.
Each step resolves credentials at execution time. If a credential is rotated mid-run, subsequent steps will use the new value. Already-executing steps continue with the value they retrieved.
Credentials are available in **Code Execution** steps and **Agent** steps via the `credential()` function. They cannot be used in workflow configuration fields or template strings.
There's no strict limit, but we recommend keeping credentials organized and removing unused ones to maintain clarity.
No. Credentials are scoped to a single workspace. Each workspace has its own isolated set of credentials.
Workflow-scoped credentials take priority. If a workflow has a Workflow-scoped credential with key `API_KEY` and the workspace also has `API_KEY`, the workflow will use its own workflow-scoped value. Other workflows without a workflow-scoped `API_KEY` will continue using the workspace value.
The workflow will fail with a `missing_credential` error when it tries to access the credential not in the allowlist. Make sure to test your workflows after configuring an allowlist.
Yes. The allowlist controls which credential keys are accessible, and workflow-scoped credentials provide the values. If a key is in the allowlist, the system will first check for a workflow-scoped value, then fall back to workspace credentials.
Credential values can be up to 64KB. For larger secrets, consider storing them in a dedicated secret manager and using a credential to store the access token.
## Summary
| Feature | Description |
| -------------- | ------------------------------------------------------------------------- |
| **Storage** | Encrypted key-value pairs in workspace settings |
| **Access** | Via `credential("KEY")` function in Code Execution and Agents |
| **Scope** | Workspace-level or workflow-level (with override capability) |
| **Allowlist** | Optional list of permitted credentials per workflow |
| **Security** | AES-256-GCM encryption, never logged or exposed |
| **Management** | Create, update (rotate), delete via Workspace Settings or Workflow header |
Credentials provide a secure, centralized way to manage sensitive values across your workflows, eliminating the need for hardcoded secrets and simplifying key rotation. With workflow-scoped credentials and allowlists, you have fine-grained control over which secrets each workflow can access.