Skip to main content

Managing Credentials in Calabi Automate

Professional+

Credentials are the secure store for all authentication details used by Calabi Automate nodes — API keys, OAuth tokens, SMTP passwords, and webhook secrets. All credentials are encrypted at rest using AES-256 and are never exposed in plain text after initial entry.

Credential Storage Architecture​

Calabi Automate stores credentials in an encrypted database table within the Calabi metadata database. The encryption key is derived from the CALABI_AUTOMATE_ENCRYPTION_KEY Kubernetes secret, which is provisioned at deployment time and rotated by your platform administrator.

┌─────────────────────────────────────┐
│        Calabi Automate Service       │
│                                     │
│  ┌──────────────────────────────┐   │
│  │  Credential Vault (AES-256)  │   │
│  │  ┌──────────────────────┐   │   │
│  │  │ Encrypted credential  │   │   │
│  │  │ data (JSON blob)      │   │   │
│  │  └──────────────────────┘   │   │
│  └──────────────────────────────┘   │
│           ↑ decrypted in memory     │
│           only during node exec     │
└─────────────────────────────────────┘

Credential values are decrypted only at execution time, in memory, and are never written to execution logs.

Credential Types​

TypeUsed ByAuthentication Method
Slack APISlack nodeOAuth 2.0 Bot Token
Email (SMTP)Email nodeUsername + password / TLS
HTTP Header AuthHTTP Request nodeCustom header (e.g., Authorization: Bearer)
HTTP Basic AuthHTTP Request nodeUsername + password
HTTP OAuth 2.0HTTP Request nodeClient credentials / authorization code
AWSS3, SNS, SES nodesAccess Key ID + Secret, or IAM role
Database (PostgreSQL)Postgres nodeHost, port, DB, username, password
MySQLMySQL nodeHost, port, DB, username, password
Amazon RedshiftRedshift nodeHost, port, DB, username, password
Google OAuth 2.0Google Sheets, GmailOAuth 2.0
PagerDutyPagerDuty nodeAPI key
Microsoft TeamsTeams nodeOAuth 2.0
Webhook (HMAC)Webhook nodeShared secret for signature validation
Calabi InternalAll Calabi-native nodesAuto-provisioned; no manual setup required

Adding a Credential​

Via the Credential Manager​

  1. In the Calabi Automate left sidebar, click Credentials.
  2. Click + Add Credential.
  3. Search for the credential type (e.g., "Slack API").
  4. Fill in the required fields (see type-specific sections below).
  5. Click Save — the credential is encrypted and stored immediately.
  6. Optionally set sharing (see Sharing Credentials).

Inline from a Node​

  1. Double-click a node that requires credentials (e.g., the Slack node).
  2. In the Credential dropdown, click + Create New Credential.
  3. A drawer opens with the credential form for that node type.
  4. Fill in the fields and click Save. The new credential is automatically selected in the node.

Slack Credentials​

Calabi Automate connects to Slack using a Slack Bot Token via OAuth 2.0.

Steps:

  1. Go to api.slack.com/apps and click Create New App → From Scratch.
  2. Give the app a name (e.g., "Calabi Automate") and select your Slack workspace.
  3. Under OAuth & Permissions, add the following Bot Token Scopes:
    • chat:write — post messages
    • chat:write.public — post to channels the bot is not a member of
    • files:write — upload files (needed for dashboard snapshots)
    • users:read — look up user IDs for DMs
  4. Click Install to Workspace and authorize.
  5. Copy the Bot User OAuth Token (starts with xoxb-).
  6. In Calabi Automate Credentials, create a Slack API credential and paste the token.
Credential Name:   Slack — #data-alerts
Token:             xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX

Email (SMTP) Credentials​

Use SMTP credentials for the Email (Send) node to deliver reports, alerts, and notifications.

FieldDescriptionExample
Credential NameFriendly nameSendGrid SMTP
HostSMTP server hostnamesmtp.sendgrid.net
PortSMTP port587 (STARTTLS) or 465 (SSL)
UserSMTP usernameapikey (SendGrid)
PasswordSMTP password or API keySG.xxxxxxxxxxxxx
SSL/TLSEncryption methodSTARTTLS recommended

Common SMTP providers:

ProviderHostPortNotes
SendGridsmtp.sendgrid.net587Use apikey as username
AWS SESemail-smtp.<region>.amazonaws.com587Use SES SMTP credentials
Gmailsmtp.gmail.com587Requires App Password if 2FA enabled
Office 365smtp.office365.com587Use full UPN as username
Mailgunsmtp.mailgun.org587Use Mailgun SMTP credentials

HTTP API Credentials​

For nodes that call external REST APIs, Calabi Automate supports multiple authentication patterns.

Bearer Token (Header Auth)​

Header Name:   Authorization
Header Value:  Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

API Key (Query Parameter)​

Name:   api_key
Value:  sk-xxxxxxxxxxxxxxxxxxxxxxxx

OAuth 2.0 (Client Credentials)​

FieldDescription
Grant TypeClient Credentials
Access Token URLYour IdP's token endpoint
Client IDApplication client ID
Client SecretApplication client secret
ScopeSpace-separated list of requested scopes

Calabi Automate automatically refreshes OAuth 2.0 tokens before they expire. Token refresh is handled transparently — no workflow changes required when tokens rotate.

Webhook Credentials (HMAC Validation)​

When your Calabi Automate workflow receives webhooks from external systems (e.g., GitHub, Stripe, Calabi internal events), you should validate the incoming request using an HMAC signature.

  1. Create a Header Auth credential: 
    Header Name:   X-Hub-Signature-256
    Header Value:  (leave blank — validated at runtime)
  2. In the Webhook node, enable Validate Webhook Signature.
  3. Enter the shared secret that the sending system uses to sign requests.
  4. Calabi Automate computes HMAC-SHA256(body, secret) and rejects requests that do not match.

Encrypting Credentials​

All credentials are automatically encrypted using AES-256-GCM before being written to the database. The encryption key is managed as a Kubernetes secret:

# Kubernetes secret — managed by your platform admin
apiVersion: v1
kind: Secret
metadata:
  name: calabi-automate-encryption
  namespace: calabi-tenant-<id>
type: Opaque
data:
  CALABI_AUTOMATE_ENCRYPTION_KEY: <base64-encoded-32-byte-key>

Key rotation procedure:

  1. Generate a new 32-byte random key: 
    openssl rand -base64 32
  2. Update the Kubernetes secret with the new key.
  3. Re-encrypt all credentials by running the re-encryption job: 
    kubectl exec -n calabi-tenant-<id> deploy/calabi-automate -- \
      node bin/re-encrypt-credentials.js --old-key <old> --new-key <new>
  4. Rolling restart the Calabi Automate pods to pick up the new key.
Backup Before Rotation

Always export and backup all credentials before rotating the encryption key. If the old key is lost before re-encryption completes, credentials cannot be recovered.

Sharing Credentials Between Workflows​

By default, a credential is accessible only to the user who created it. You can share credentials with other workspace members.

Sharing Steps​

  1. Open Credentials in the left sidebar.
  2. Click the ••• menu on a credential → Edit.
  3. Under Sharing, click + Add Users or Roles.
  4. Select workspace members or roles to grant access.
  5. Choose permission level:
    • Use — can select this credential in nodes but cannot view or edit values.
    • Edit — can view and modify credential values.
  6. Click Save.

Sharing Levels​

LevelCan Use in WorkflowsCan View Secret ValuesCan EditCan Delete
OwnerYesYesYesYes
EditYesYesYesNo
UseYesNoNoNo
Team Credentials Best Practice

Create credentials under a shared service account and grant Use permission to all workflow authors. This way, secret values remain visible only to administrators while everyone can build workflows that use them.

Testing Credentials​

Before using a credential in a live workflow, verify it works:

  1. Open Credentials → select the credential.
  2. Click Test Credential (available for most types).
  3. Calabi Automate makes a low-impact API call (e.g., Slack auth.test, SMTP EHLO) and reports success or a descriptive error.

Auditing Credential Usage​

To see which workflows use a given credential:

  1. Open Credentials → click a credential name.
  2. The Workflows Using This Credential section lists all workflows that reference it.
  3. Clicking a workflow name opens it in the canvas editor.

This audit view is particularly useful before rotating or deleting credentials — verify no active workflows depend on them.

Deleting Credentials​

  1. Open Credentials → ••• → Delete.
  2. If any active workflows reference the credential, you will see a warning listing them.
  3. Deactivate and update all listed workflows before proceeding.
  4. Confirm deletion — credential values are permanently and irrecoverably removed from the encrypted store.