OAuth Connections
Poll a vendor API that authenticates with OAuth — the platform resolves the connection's account and hands your source a live access token
A declarative poll source names the credential it needs with authRef. When the connection an organization configured for that source is an API key, authRef resolves to credentials.apiKey. When it is an OAuth connection, it resolves to credentials.accessToken — a token that is current at the moment your tick runs.
Nothing in the manifest chooses between the two. The organization chooses when it configures the connection; the platform resolves whichever one that connection carries.
What the platform hands your source
| Connection auth mode | credentials field you receive |
|---|---|
api_key, bot_token | apiKey |
oauth, oauth_app, oauth_client_credentials | accessToken |
none | (no credential — the source is keyless) |
basic_auth | (refused — a username and password is not one secret to place on a request; the tick returns HTTP 412 data_source_connection_required) |
Place it with request.auth. credential: "accessToken" sends the OAuth token where the vendor expects it:
request: {
url: "https://graph.microsoft.com/v1.0/me/messages",
authRef: "primary",
auth: { placement: "bearer", credential: "accessToken" },
}credential names a field, not a value. A manifest never contains a token, a client id, or a client secret — those live on the connection the organization configured, and only the platform reads them.
Token freshness is the platform's job, not yours
The platform resolves the token on every tick, immediately before your request is built:
- It finds the connection's default execution account.
- It checks that account's expiry and, if the token is at or near expiry, exchanges the stored refresh token (or, for
oauth_client_credentials, re-acquires with the client credentials) and persists the result. - It hands your source the resulting access token.
So a poll source never sees a stale token, and never needs refresh logic of its own.
Your source receives the access token and nothing else. The refresh token, the client secret and the expiry stay inside the platform. There is deliberately no way for a data source to mint a new credential — it can only spend the one it was given, for the one tick it was given it for.
When the connection needs attention
If the platform cannot produce a live token, the tick does not run and the source reports a configuration problem rather than a request failure. That happens when:
- the connection has no account connected yet (nobody completed the OAuth sign-in);
- the account was marked as needing reauthorization (consent revoked, password changed, admin removed the app);
- the refresh itself failed at the vendor.
All three surface the same way as a missing API key: the platform raises CAPABILITY_NOT_CONFIGURED, and the data-source tick returns HTTP 412 with error: "data_source_connection_required". The fix is always the same — reconnect the account on the connection in organization settings.
An account is only ever resolved from the same organization and the same connection the source is bound to. An account connected for a different organization, or anchored to a different connection, is never borrowed — the tick reports data_source_connection_required instead.