Production Best Practices

Secure your workflows, manage credentials, debug failures, and operate Orchestrator at production scale.

What you'll learn in this module

How Orchestrator encrypts and stores credentials
Best practices for key management and workflow visibility
A systematic approach to debugging failed executions
Performance patterns and common pitfalls to avoid

Security Model

Orchestrator uses a multi-layer security architecture. Understanding it helps you make informed decisions about credential storage and workflow sharing.

Credential Encryption

Layer	Mechanism
Integration credentials	AES-256-GCM encryption at rest. Decrypted only during execution, never logged.
API keys	SHA-256 hashed before storage. The full key is returned exactly once at creation.
Execution logs	Inputs and outputs are auto-redacted. Auth headers, tokens, and keys are stripped.
Session auth	Management API uses HTTP-only session cookies, not bearer tokens.

Key Separation

Orchestrator uses two distinct types of keys:

Key Type	Purpose	Scope
Orchestrator API Key	Authenticate webhook requests to a specific workflow	Per-workflow
Skytells Platform Key	Authenticate calls to Skytells AI models (AI Gateway, etc.)	Per-account

Never use your Skytells Platform key as a webhook API key. The Orchestrator API key is scoped to a single workflow and provides least-privilege access.

Credential Management Best Practices

Use dedicated credentials per workflow

Create a separate integration for each workflow rather than sharing one integration across many workflows. This allows you to revoke access for a single workflow without affecting others.

Test integrations before deploying

Use the Test button (or POST /api/integrations/{id}/test) to verify credentials before enabling a webhook trigger.

Rotate keys on schedule

Update integration credentials periodically. Since Orchestrator decrypts at runtime, updating the integration immediately takes effect for all future executions.

Audit API key usage

Orchestrator shows only the key prefix in the dashboard. If you suspect a key is compromised, delete it immediately via the API Keys panel and create a new one.

Workflow Visibility

Every workflow has a visibility setting:

Visibility	Who can view	Who can execute
`private`	Owner only	Owner + anyone with API key
`public`	Anyone with the link	Owner + anyone with API key

Public visibility only affects the workflow editor view — it never exposes credentials or execution logs. API key authentication is always required for webhook execution regardless of visibility.

Debugging Failures

When an execution fails, follow this five-step process:

Step 1 — Check the Execution Status

Open the workflow and click the Executions tab. Look for the execution with error status.

Step 2 — Identify the Failed Step

Click into the execution to see the per-step breakdown. Each step shows its own status. The first step with error is usually the root cause.

Step 3 — Read the Error Details

The step log entry includes:

error — the error message or code
input — what was sent (redacted)
output — any partial response
duration — how long before failure

Step 4 — Common Error Patterns

Error	Likely cause	Fix
`401 Unauthorized`	Expired or invalid integration credentials	Update integration with fresh credentials
`429 Too Many Requests`	Rate limit hit on external service	Add delays or reduce parallel actions
`TIMEOUT`	External API took too long	Check service status; consider breaking into smaller steps
`INVALID_TEMPLATE`	Bad template variable syntax	Verify `{{step_name.field}}` references exist upstream
`INTEGRATION_NOT_FOUND`	Missing integration on an action	Re-attach the integration in the action config
`CONDITION_EVAL_ERROR`	Invalid condition expression	Check operator compatibility and value types

Gate with conditions — check whether the AI call is needed before making it
Be specific in prompts — shorter, focused prompts return faster
Use the right model — don't use a large model for simple classification

Template variable efficiency

Template variables are resolved at execution time. Keep variable paths short:

{{step_1.text}} — fast, one-level access
{{step_1.deeply.nested.field.value}} — works, but harder to debug

Execution Log Best Practices

Practice	Reason
Review logs after first production run	Catch unexpected outputs early
Delete old executions periodically	Execution data accumulates; use the delete endpoint to clean up
Don't rely on logs for data storage	Logs are redacted and not designed as a data store
Check log redaction	Verify sensitive data isn't leaking through custom output fields

Pre-Launch Checklist

Before switching a workflow from Manual to Webhook trigger:

All integrations tested via the Test button
Template variables verified with a Manual run + sample data
Condition branches tested with edge-case inputs
Error handling considered — what happens when an external API is down?
API key created and stored securely in the calling system
Execution logs reviewed for any sensitive data exposure
Workflow visibility set appropriately

What you now understand

Area	Key takeaway
Encryption	AES-256-GCM for credentials, SHA-256 for API keys, auto-redaction for logs
Key separation	Orchestrator keys ≠ Skytells keys — always use the right key for the right scope
Debugging	Five-step process from execution status → step error → fix → re-run
Performance	Split large workflows, gate expensive actions, use focused prompts
Pre-launch	Eight-point checklist before going to production

Congratulations — you've completed the Orchestrator Mastery learning path. You now have the knowledge to build, integrate, automate, and operate workflows in production.

Explore the Orchestrator documentation for complete API reference and plugin details.

PreviousAPI & Automation