API reference
OctaveAuthClient
Browser OAuth client for Sign in with Octave, using the authorization code flow with PKCE.
import { OctaveAuthClient } from "@octave-ams/auth-sdk";Constructor
new OctaveAuthClient(config: OctaveAuthConfig)| Option | Type | Description |
|---|---|---|
| domain | string | Hosted sign-in base URL, without a trailing slash. |
| clientId | string | OAuth client ID from your app registration. |
| redirectUri | string | Where Octave returns after sign-in. |
| logoutRedirectUri | string? | Where Octave returns after sign-out. |
| scopes | string[]? | Requested scopes. Defaults to openid, email, profile. |
Properties
| Property | Value |
|---|---|
| authorizeUrl | {domain}/oauth2/authorize |
| tokenUrl | {domain}/oauth2/token |
| logoutUrl | {domain}/logout |
Methods
buildSignInUrl
buildSignInUrl(options?: { loginHint?: string; identityProvider?: string }): Promise<string>Creates a PKCE pair and a state value, stores them in session storage, and returns the authorize URL. Pass identityProvider (for example Google) to go straight to a social provider, or loginHint to prefill the email.
signInRedirect
signInRedirect(options?: { loginHint?: string; identityProvider?: string }): Promise<void>Builds the sign-in URL and navigates to it.
handleCallback
handleCallback(callbackUrl?: string): Promise<OctaveAuthTokens>Reads the code and state from the callback URL (the current URL by default), checks the state, and exchanges the code and PKCE verifier at the token endpoint.
signOutRedirect
signOutRedirect(): voidNavigates to the logout endpoint, returning to your logout URI.
Tokens
| Field | Type | Description |
|---|---|---|
| accessToken | string | For calling Octave APIs. |
| idToken | string | Identifies the signed-in user. |
| refreshToken | string? | For getting new tokens, when issued. |
| expiresIn | number? | Seconds until the access token expires. |
| tokenType | string? | Usually Bearer. |
Helpers
| Export | Returns |
|---|---|
| generatePkcePair() | Promise<{ verifier, challenge }> — an S256 PKCE pair. |
| generateState() | string — a random OAuth state value. |
Errors
| Message | Cause |
|---|---|
| Missing authorization code | The callback URL has no code. |
| Missing PKCE verifier — start sign-in again | Session storage was cleared mid-flow. |
| Invalid OAuth state — possible CSRF | The returned state doesn't match the one sent. |
| Token exchange failed: … | The token endpoint rejected the request. |