Credentials
A workflow never holds a password. Access data lives in one of two per-tenant stores, and a node references it by name:
- A credential is a structured, testable connection to one external system — an SMTP server, an SFTP account, an API. It knows its own fields, it can test itself, and where a token has to be refreshed it manages that itself. This page.
- A secret is a single opaque string under a key. The platform stores it and hands it back to a node at execution time without knowing what it is. See Secrets.
Neither one puts a value into the workflow document. A node that needs access declares a credential reference (naming the credential type it needs) or a secret reference (holding a key), and the resolved value never enters the workflow definition or the run history.
Credentials are managed in Cockpit, under Integration Studio → Credentials.
Types and instances
A credential type is published by a node package. It declares its own fields with their validation, how it authenticates, and how to test itself. A credential instance is one filled-in copy of a type on your tenant, with a name you choose — and you can keep as many as you need: three SMTP servers and two SFTP accounts is an ordinary setup. Names are unique per tenant.
A node declares which type it needs, and the field then offers only your instances of that type. The runtime resolves the concrete instance when the node executes.
Six types ship with the platform's own node package:
| Type | Slug | Used by |
|---|---|---|
| SMTP | revenexx:smtp | Send Email |
| SFTP | revenexx:sftp | the SFTP nodes, and the staging and delivery nodes that stream to and from SFTP |
| FTP | revenexx:ftp | the FTP nodes |
| HTTP Bearer Token | revenexx:http-bearer | HTTP Request |
| DeepL | revenexx:deepl | DeepL Translate |
| Revenexx API | revenexx:api | Generic API Call, the platform storage nodes, and the import and export nodes |
The Revenexx API credential is scoped, and the scope matters: the import and export nodes need one carrying the io scope. A credential that tests fine but lacks the scope fails at the step, not at the test. See Reaching Revenue Cloud.
The five auth kinds
Every type declares one, and it determines what the create form asks for and what the runtime hands the node:
| Auth kind | What it means |
|---|---|
static | The fields are the access data — host, username, password. Used by SMTP, SFTP and FTP. |
api-key | A single key, handed to the node as such. |
basic | A username and password pair. |
oauth2-client-credentials | A client id and secret are exchanged for a short-lived access token on each resolve. |
oauth2-authcode | Three-legged OAuth. A stored refresh token is exchanged for an access token, and the refresh token is rotated as the provider requires. See OAuth. |
Access tokens are never stored on the workflow or in a run's history. They are resolved as the node executes, so a retried step gets a fresh token rather than replaying a stale one.
Creating one, and testing before you save
Creating a credential is two steps: pick the type from a searchable list, then fill the form the type declares. Secret-typed fields are masked as you type. Required fields are marked, and the labels are the ones the system uses, so an SFTP form asks what an SFTP admin would expect.
Test before you save. The dialog can run the type's own connection test against the values you have typed, without creating anything. A passing test says so; a failing one shows the service's own reason rather than a generic failure. Get a green test in the dialog and you have removed the most common cause of a workflow that fails on its first run.
A saved credential can be tested again at any time from its detail view. The result is recorded, which is what the list and the node's credential picker read when they show whether a credential works.
The four positions
A credential reports one of four positions:
- Connected — its last test passed.
- Failed — its last test failed, and the reason it failed is kept alongside it.
- Not connected — it has never been tested. This is not a quiet success; test it.
- Needs reconnect — its authorization has expired. This outranks a passing test: a credential whose last test passed but whose authorization has since lapsed reads as needing a reconnect, because that is what will happen on the next run.
Needs reconnect only applies to types that hold an authorization rather than a static password — see OAuth for what re-authorizing involves.
Editing and deleting
Editing pre-fills the ordinary values and leaves the secret fields blank. A secret field left blank keeps the stored value — including one you typed into and then cleared — so you can change a host without re-entering a password.
Deleting is not scoped: every workflow that references the credential fails on its next run until it is re-bound to another one. Cockpit warns about that in the abstract but cannot yet name which workflows are affected, so check before you delete.
Which one to use
Reach for a credential whenever the target is a system with a shape — a mail server, a file server, an API with an auth flow. You get validation, a test button, token handling, and one place to fix it when the customer rotates their password.
Reach for a secret for a single opaque string that no credential type covers: a shared token a partner's endpoint expects in a custom header, a signing key one of your own nodes reads.
If you find yourself keeping a host, a username and a password as three separate secrets, that is a credential type waiting to be written — a node package can publish one alongside its nodes. See the Integration Node SDK.
Where to go next
- OAuth — the three-legged flow, and re-authorizing.
- Secrets — the other store.
- Node catalog — which nodes ask for which credential type.
- Templates — the readiness check that counts credentials for you before you install one.
- Import a BMECAT product catalog — a template that needs exactly two credentials, wired end to end.