OAuth

Two of the five auth kinds are OAuth, and they behave differently enough to be worth separating.

oauth2-client-credentials is machine-to-machine. The credential holds a client id and a client secret, and the platform exchanges them for a short-lived access token every time a node resolves the credential. There is nothing interactive about it: fill the form, test it, done.

oauth2-authcode is three-legged, and involves a human once. That is the flow this page is about.

The flow

Saving an oauth2-authcode credential is not the end of it. The credential exists but is not yet usable, and Cockpit walks you through the rest:

1. Authorize. A separate window opens, pointed at the provider.
2. The provider. You sign in there and consent to the access the credential is asking for. This happens entirely between you and the provider — the studio never sees the provider password, and the credential never stores it.
3. The callback. The provider hands the platform an authorization it exchanges for two things: a short-lived access token and a long-lived refresh token. Only the refresh token is stored.
4. Usable. The credential becomes usable once that window reports back. Until then, a node referencing it has nothing to resolve.

From then on, every time a node resolves the credential the stored refresh token is exchanged for a fresh access token. The access token is never persisted — not on the workflow, not in the run history — which is why a retried step gets a current token rather than replaying a stale one.

Refresh rotation

Many providers rotate the refresh token on every exchange: the response carries a new refresh token, and the one you sent becomes invalid. The platform stores the new one as part of the exchange, so rotation is handled for you and there is nothing to do on your side.

The consequence worth knowing is that a credential's stored authorization is live state, not configuration. Two things follow from that:

• Do not expect to move a credential between tenants or environments by copying its fields. Authorize it where it is used.
• An authorization can be revoked at the provider — by an admin, by a password change, by a policy — without anything on the platform side changing. The credential keeps reading as connected until the next exchange fails.

When an authorization lapses

A lapsed authorization moves the credential to Needs reconnect. That position 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.

Reconnecting is one action. The credential offers Reconnect, which reopens the provider window and runs the same three legs again. Nothing else about the credential changes, and no workflow has to be re-wired — nodes reference the credential instance, not the authorization inside it, so every workflow that used it keeps working from the next run.

Practically: when a customer says "the integration stopped last Tuesday", check the credential list for Needs reconnect before you look at anything else.

Where to go next

• Credentials — the other three auth kinds, testing, and the four positions.
• Secrets — for access data no credential type models.
• Custom nodes — publishing a credential type of your own alongside your nodes.
• Auth — the platform's own authentication, which is a different thing from a workflow's outbound credentials.