Credentials

Orchka provides a secure credential management system for storing and using API keys, tokens, and authentication details in your workflows.

Overview

Instead of hardcoding sensitive values in your workflow nodes, you can:

1. Store credentials securely with AES-256-GCM encryption
2. Reference credentials by ID in your nodes
3. Credentials are decrypted only during workflow execution

Credentials are scoped to your active organization — switching orgs in the sidebar narrows the list to that org's credentials. See Organizations & Teams for the multi-tenant model.

Credential Types

Creating Credentials

1. Navigate to Credentials in the dashboard sidebar
2. Click New Credential
3. Select the credential type
4. Enter a unique name and the required fields
5. Click Create

Finding Credentials

The credentials list supports:

• Search by name (partial, case-insensitive)
• Type filter in the toolbar — a dropdown grouped by category (Generic / AI Providers / Social). Selecting a type writes ?type=… to the URL, so filtered views are shareable.
• Scalable pagination with truncation, "X–Y of N" summary, and a "Go to page" popover on the ellipsis

Filtering happens in the database query, not the client.

Using Credentials in Nodes

AI Agent Node

Select a stored credential instead of relying on environment variables:

1. Open the AI Agent node settings
2. In the Credential dropdown, select your saved credential
3. The credential type must match the selected model provider

Model: gpt-4o
Credential: My OpenAI Key (OpenAI type)

HTTP Request Node

Use credentials for API authentication:

1. Open the HTTP Request node settings
2. Set Auth Type to "Credential"
3. Select the appropriate credential

Supported credential types for HTTP:

• Bearer Token → Authorization: Bearer <token>
• Basic Auth → Authorization: Basic <base64>
• API Key → X-API-Key: <key>

Social Media Nodes

Social nodes use dedicated credential types so each platform can validate the fields it needs:

Testing Credentials

Before using a credential in production:

1. Open the credential details
2. Click Test Credential
3. For AI provider credentials, this validates the API key with the provider
4. Generic and social credentials are schema-validated; platform-side permission errors surface when the workflow runs

Security

• Encrypted at rest with AES-256-GCM, using a master key held only in CREDENTIAL_ENCRYPTION_KEY
• Decrypted only during workflow execution, in the worker process
• Secrets are never returned by the API. There is no endpoint that reads a credential back in plaintext — the list and detail views return metadata only
• Access is scoped by organization: a workflow can use a credential only if both belong to the same org. That is what lets teammates share one credential, and what stops a workflow in one org using another org's
• Every create, update, delete and execution-time resolution writes a row to the credential audit log

Environment Setup

Generate an encryption key for your deployment:

# Generate a 32-byte hex key (exactly 64 hex characters)
openssl rand -hex 32

Set it as CREDENTIAL_ENCRYPTION_KEY. Three things to know:

• It is validated at boot. A missing or malformed key stops the process starting, rather than failing later when someone opens a credential.
• The web and worker processes must use a byte-identical value. A mismatch does not error — it silently produces credentials that cannot be decrypted.
• Back it up. There is no recovery path and no rotation mechanism: lose the key and every stored credential is permanently unreadable.

Add to your .env:

CREDENTIAL_ENCRYPTION_KEY=your_64_character_hex_key_here

Best Practices

1. Use descriptive names - "Production OpenAI" vs "test-key-1"
2. Rotate credentials regularly - Update credentials without changing workflows
3. Test before deploying - Use the test feature to validate credentials
4. One credential per purpose - Easier to track and rotate