OAuth

OAuth is Jingle's authorization model for public connected accounts. An extension starts authorization, Jingle opens the provider consent page, the callback returns to Jingle, and tokens are stored securely by the platform.

Target flow

Extension command
  -> create OAuth client
  -> Jingle creates state + PKCE verifier
  -> browser opens provider consent page
  -> provider redirects to Jingle callback
  -> Jingle validates state and exchanges code
  -> credential store saves token set
  -> extension receives connected status

Why PKCE

Desktop apps and extensions are public clients. They cannot safely keep a client secret. PKCE binds the authorization request and token exchange through a code verifier / code challenge pair, reducing the risk of intercepted authorization codes.

Public OAuth integrations should use:

• authorization code flow;
• state validation;
• PKCE S256;
• token exchange in the main process or a trusted backend;
• platform-owned refresh and revoke.

Redirect methods

Jingle plans to support these callback shapes:

The callback page can display code, state, or error returned by a provider. State validation, code exchange, token refresh, and revoke will be handled by the platform OAuth service.

Manifest shape

connection: {
  id: "default",
  provider: "notion",
  title: "Notion",
  auth: {
    type: "oauth",
    authorizationUrl: "https://api.notion.com/v1/oauth/authorize",
    tokenUrl: "https://api.notion.com/v1/oauth/token",
    clientId: "client-id",
    scopes: [],
    secretNames: ["accessToken"],
    redirect: {
      method: "web",
      redirectUrl: "https://jingle.ai/callback?packageName=notion"
    }
  }
}

You can declare the OAuth shape now; production authorization should wait for the platform OAuth service.

Extension author API

Extension authors should declare a provider and call the platform OAuth API instead of implementing browser handoff, callbacks, and token storage themselves:

import { OAuth } from "@openwork/extension-api"

const client = new OAuth.PKCEClient({
  redirectMethod: OAuth.RedirectMethod.Web,
  providerName: "Notion",
  description: "Connect your Notion workspace"
})

Developer Preview:

• OAuth.PKCEClient constructor
• OAuth.RedirectMethod.Web

Planned:

• authorizationRequest()
• authorize()
• setTokens()
• getTokens()
• removeTokens()
• logout preference
• refresh token lifecycle
• revoke

Provider strategy