grove.oauth.authorize()

Run a user-visible OAuth Authorization Code session using host-generated state and PKCE material.

Signature

grove.oauth.authorize(authorizationURL: string, options?: {
  transactionID?: string; prefersEphemeralSession?: boolean
}): Promise<{
  readonly code: string; readonly codeVerifier: string
  readonly redirectURI: string; readonly callbackURL: string
}>

Availability

Runtime with oauth.authorize and an HTTPS authorization URL matching accepted hostPermissions. Prefer an exact authorization origin; supported wildcard host patterns still follow the sandbox’s matching rules. Settings pages cannot authorize.

Parameters

Return value

Resolves to a frozen object after callback validation. code is the one-time authorization code; codeVerifier is the host-generated PKCE verifier for exchange; redirectURI is mango://grove/oauth; callbackURL is the complete validated provider callback. It does not return access or refresh tokens.

Behavior and errors

Direct flow removes extension-supplied response_type, redirect_uri, state, code_challenge, and code_challenge_method, then inserts host values. The final URL must also fit the bound. Brokered flow uses the supplied URL unchanged with the prepared verifier/state. A matching prepared transaction is consumed before URL validation/session start; prepare again after an attempted flow fails.

Broker trust boundary: Mango does not inspect a brokered URL for the prepared redirect_uri, state, code_challenge, or code_challenge_method. The broker must send those exact values to the authorization provider and require S256 PKCE during code exchange. Generating a verifier and validating callback state does not prove the broker/provider used PKCE. Use a trusted broker whose integration enforces that contract; use the direct flow when the extension can construct the provider URL itself. Neither flow makes an untrusted authorization provider safe.

Rejects on missing grants, invalid/ungranted URL, missing/reused transaction, concurrent app-wide authorization, failed start, cancellation, provider rejection, invalid callback, or state mismatch. Callback permits only the fixed scheme/host/path, no credentials/port/fragment, no duplicate critical fields, and a nonempty code of at most 4,096 UTF-8 bytes. Error strings are not stable codes. The extension exchanges the code, refreshes tokens, and stores credentials itself.

Example

async function signIn() {
  try {
    const url = new URL('https://identity.example.com/authorize')
    url.searchParams.set('client_id', 'public-client-id')
    url.searchParams.set('scope', 'profile')
    const authorization = await grove.oauth.authorize(url.toString())
    // Exchange authorization.code with authorization.codeVerifier.
    // Never log this object or embed a confidential client secret.
  } catch {
    console.error('Sign-in did not complete.')
  }
}

See OAuth integrations for complete direct and brokered examples.