Connect an OAuth account¶
Use OAuth to give Nuvoca access to an external account, such as a calendar. Set up the connection under Settings → Credentials. You need an application registered with the provider and the required permissions, usually called scopes.
Choose the authorization method¶
| Grant | Use when | Setup |
|---|---|---|
| Client Credentials | The provider explicitly supports server-to-server access with this grant | Client ID, secret, token URL and scopes |
| Authorization Code + PKCE | A user must authorize account access | Authorization URL, token URL, client ID, required secret, scopes and exact redirect URI |
Copy the redirect URI shown in Nuvoca and register it with the provider exactly as displayed. Supply a client secret for PKCE if the provider requires one.
Authorize and test¶
- Create the configuration with the provider's values and header prefix, usually
Bearer. - For PKCE, save and open PKCE Authorization from the configuration menu.
- Complete the provider's sign-in and consent flow.
- Run the credential test. PKCE needs a stored refresh token for this test.
- Select the credential in your integration and test the actual resource endpoint.
If sign-in succeeds but the actual request is denied, check the scopes and account permissions with the provider.
Example: Google Calendar¶
Enable Calendar API, register a web application and use Nuvoca's exact redirect URI. For read-only calendar access, use a suitable read scope such as https://www.googleapis.com/auth/calendar.readonly. Google's token endpoint is https://oauth2.googleapis.com/token. Request offline access when refresh tokens are needed. Follow Google's web-server OAuth guide for registration, consent and provider requirements.
Maintain the connection¶
| Action | Effect |
|---|---|
| Test | Attempts token acquisition or refresh. |
| Invalidate Token | Clears the cached access token so a later request obtains a new one. |
| Revoke Credentials | Clears Nuvoca's stored authorization. PKCE authorization must be completed again. |
| Edit | Update configuration, then retest affected integrations. |
| Delete | Requires resolving displayed usages before deletion can proceed. |
Review usages in tools, MCP connections and processing before removal. Clearing Nuvoca's credentials is distinct from revoking permissions in the provider's account settings.
Common errors¶
For a redirect error, make sure the URI in Nuvoca matches the one registered with the provider. If token refresh is not authorized, reconnect the account with the provider’s required settings. For a grant error, check the authorization method. For APIs that use a fixed key, choose API key credentials.