OAuth in Applications
The admin guide to setting up OAuth providers, configuring MCP servers and controlling what your organization's Charms can access.
|
|
Applications Can Connect Too
window.charmiq) provides a first-class secure OAuth pathway that bypasses those restrictions.The Application Bridge OAuth API
// 1. Request authorization with a provider const auth = await window.charmiq.oauth.getValidAuth({ providerUrl: 'https://accounts.google.com', scopes: ['https://www.googleapis.com/auth/analytics.readonly'], }); // auth.accessToken — use this in your API calls // 2. Revoke access when done await window.charmiq.oauth.revokeAuth(auth);
getValidAuth opens a consent popup managed by CharmIQ (the iframe can't open popups directly due to browser sandboxing). The consent dialog shows your Application's name as CharmIQ resolves it and, for signed Applications, the publisher. Once the user authorizes, CharmIQ returns the access token to your Application. All tokens are encrypted and stored server-side — your Application receives the token in memory; it's never exposed in client storage.getValidAuth always returns a valid token — call it again before a batch of API calls rather than caching the token, and CharmIQ refreshes expired tokens behind the scenes.For Developers — window.charmiq.oauth.register()still exists as a legacy no-op: it resolves successfully and any config you pass to it is ignored. New Applications skip it and callgetValidAuth()directly.
Multiple Accounts
const accounts = await window.charmiq.oauth.listAuth({ providerUrl: 'https://accounts.google.com' }); // each account carries displayIdentifier, integrationId, providerAccountId — no token const auth = await window.charmiq.oauth.getValidAuth({ providerUrl: 'https://accounts.google.com', connectionKey: account.id, // the account the user chose });
listAuth opens no popup and returns no tokens, but shares its consent grant with getValidAuth — allowing it grants token access (allow once; later per-account getValidAuth calls don't re-prompt), and a denied listAuth rejects, so handle it. The same login connected through two Integrations returns two descriptors with equal providerAccountId but different integrationId; dedupe on whichever you prefer. To add another account, call getValidAuth({ prompt: 'select_account' }).Token Isolation
Two Applications connecting to the same provider for different purposes are fully independent You can revoke one Application's access without affecting another Users can see and manage each Application's connections separately An inline Application's connections are scoped to the document that hosts it — the same content pasted into another document asks for authorization again there. Folder-based Applications hold one connection wherever they're embedded.
Provider Setup
getValidAuth fails with an authorization error, the Integration for that provider likely hasn't been set up yet.For Developers — The Application Bridge's getValidAuthcall results in a Connection scoped toapplicationType: Applicationand the Application CharmIQ resolved when it loaded — never a value your code supplies. This is the same Connection model used by MCP servers, just with a different type discriminator. From a security standpoint, the token lifecycle and encryption are identical. The bridge serializes all OAuth communication throughpostMessagesince the iframe cannot communicate directly with CharmIQ's backend.
Patterns
Authorize on demand. Call getValidAuthonly when the user actually needs the connected feature — not upfront. There's no identity setup step to call first.Revoke when the session ends. If the OAuth connection was for a specific task, revoke it when the user is done. Don't accumulate live tokens.