OAuth connections

Some services (Google, Microsoft, Slack…) are not accessed with a username and password but with OAuth: you authorize Zoan Automation to act on your behalf from the provider’s own consent screen, and it hands back an access token. Zoan Cloud OAuth connections store and manage those tokens for you.

Connection vs. credential

A credential stores static secrets (username, password, token). An OAuth connection represents an authorization over a third-party account: it stores the access token and its refresh_token, and Zoan Cloud refreshes it automatically when it expires. In the playbook both are referenced the same way: = credential("name").

How it works

1. You create the connection   →  status: pending
2. You click "Authorize"        →  the provider's consent screen opens
3. You approve access           →  status: connected (token stored)
4. The bot uses it by name      →  Zoan Cloud hands back a valid token (auto-refreshed)

The provider (Google, Microsoft, etc.) is set up once by the platform administrator. In your tenant you only create connections over the available providers.

Create a connection

1. Open the Connections menu.
2. Click New Connection.
3. Pick the provider (e.g. Google).
4. Define two names:
   • Code name: lowercase letters, numbers and hyphens only (e.g. google-clinic-calendar). This is the name you reference in the playbook.
   • Display name: shown in the portal (e.g. Google Clinic Calendar).
5. Check the permissions (scopes) the bot needs.
6. Click Create and Authorize: the provider opens so you can approve access.

It must end up “Connected”

A newly created connection stays pending until you complete the authorization. If a bot uses it while pending, it fails with “could not resolve credential”. Make sure the card shows Connected before using it.

Code name vs. display name

In activities you always reference by the code name (the lowercase-hyphen one), not the display name:

Google Sheets — Open   credential = "google-clinic-calendar"

Using the display name gives the error “credential does not exist”.

Permissions (scopes)

Each provider offers a catalog of scopes (what the bot may do: read Gmail, write Sheets…). Pick only what you need — least privilege. If the provider has no scopes configured, you cannot create connections with it; ask the platform administrator to add at least one.

Connections live in an environment

Like credentials, a connection belongs to an environment (or is global for all). This way the same playbook uses the test account in Test and the real one in Production, referencing the same code name in both. See Environments.

Connection states

State	Meaning
Pending	Created but not authorized. Cannot be used yet.
Connected	Authorized and ready. Zoan Cloud refreshes the token automatically.
Expired	The refresh failed (e.g. access revoked at the provider). Click Reconnect.
Error	Problem refreshing. Re-authorize with Reconnect.

Reconnect or revoke

• Reconnect: repeat the consent to renew the authorization (after expiry or to switch accounts).
• Delete: revokes the token at the provider (best effort) and removes the connection.

Next steps

• Bring Your Own App (BYOA) — use your own Google/Microsoft app instead of the shared one.
• Credentials — static secrets (username/password/token).