api.auth
Interface: IAuthApi
Implementation tier: T2
OAuth 2.0 Authorization Code flow with PKCE, token refresh, and opening external URLs.
Permissions
network:oauth
Methods
startOAuth
startOAuth(opts: StartOAuthOpts): Promise<OAuthResult>
Run the OAuth 2.0 Authorization Code flow (with PKCE by default). The
host opens a real BrowserWindow pointing at authorizeUrl, watches for
navigation to the redirect URI, captures the code and state, performs
the token exchange itself, and resolves with the result.
The redirect URI is always ext-ui://<extensionId>/<redirectPath>,
registered with the auth provider. This means the host's custom protocol
receives the redirect — no public callback server required.
Token storage is the extension's responsibility (use storage:secrets).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
opts | StartOAuthOpts | Yes |
Returns: Promise<OAuthResult>
refreshOAuth
refreshOAuth(opts: RefreshOAuthOpts): Promise<OAuthResult>
Exchange a refresh_token for a new access_token.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
opts | RefreshOAuthOpts | Yes |
Returns: Promise<OAuthResult>
openExternal
openExternal(url: string): Promise<void>
Open the user's default browser at a URL (e.g. for a settings page on
the extension's website). Requires network:oauth permission.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes |
Returns: Promise<void>