Initiates an OAuth2 authorization flow with PKCE (Proof Key for Code Exchange). This method handles both native in-app consent and web-based fallback flows.
Authorization parameters including client ID, redirect URI, scope, and environment.
The authorization result, containing the authorization code on success or redirect status.
Important Note on redirectUri and responseMode:
The actual redirectUri used during authorization may differ from the one you provide,
depending on the flow:
responseMode: 'in_place' when native flow is available: Uses the current page URL
(normalized) as the redirectUri, overriding your provided valueresponseMode: 'in_place' falling back to web flow if native flow is not available:
Uses your provided redirectUriresponseMode: 'redirect': Always uses your provided redirectUriTo ensure successful token exchange (which requires matching redirectUri values),
always retrieve the actual redirectUri from getAuthorizationArtifacts()
after authorization completes.
Consent Selection Rules (Native vs Web):
Simple usage
import { IdentityModule, isSuccess, isRedirection, isErrorResponse } from '@grabjs/superapp-sdk';
// Initialize the identity module
const identity = new IdentityModule();
// Initiate authorization with redirect mode
const response = await identity.authorize({
clientId: 'your-client-id',
redirectUri: 'https://your-app.com/callback',
scope: 'openid profile',
environment: 'production',
responseMode: 'redirect'
});
// Handle the response
if (isSuccess(response)) {
switch (response.status_code) {
case 200:
console.log('Auth Code:', response.result.code);
console.log('State:', response.result.state);
break;
case 204:
console.log('Authorization cancelled');
break;
}
} else if (isRedirection(response)) {
console.log('Redirecting to authorization...');
} else if (isErrorResponse(response)) {
switch (response.status_code) {
case 403:
console.log('Client not authorized for requested scope');
// Check OAuth client configuration and requested scopes
break;
default:
console.error(`Error ${response.status_code}: ${response.error}`);
}
} else {
console.error('Unhandled response');
}
Clears all stored PKCE authorization artifacts from local storage. This should be called after a successful token exchange or when you need to reset the authorization state (e.g., on error or logout).
Confirmation that the authorization artifacts have been cleared.
Simple usage
import { IdentityModule, isSuccess } from '@grabjs/superapp-sdk';
// Initialize the identity module
const identity = new IdentityModule();
// Clear stored authorization artifacts after successful token exchange
const response = await identity.clearAuthorizationArtifacts();
// Handle the response
if (isSuccess(response)) {
console.log('Authorization artifacts cleared');
}
Retrieves stored PKCE authorization artifacts from local storage. These artifacts are used to complete the OAuth2 authorization code exchange.
The stored PKCE artifacts including state, code verifier, nonce, and redirect URI.
Important: The redirectUri returned by this method is the actual redirect URI
that was sent to the authorization server. This may differ from the redirectUri
you provided to authorize() if you used responseMode: 'in_place' with native flow.
You must use this returned redirectUri for token exchange to ensure OAuth compliance.
Simple usage
import { IdentityModule, isSuccess, isErrorResponse } from '@grabjs/superapp-sdk';
// Initialize the identity module
const identity = new IdentityModule();
// Retrieve stored authorization artifacts after authorization redirect
const response = await identity.getAuthorizationArtifacts();
// Handle the response
if (isSuccess(response)) {
switch (response.status_code) {
case 200:
// All artifacts present - proceed with token exchange
const { state, codeVerifier, nonce, redirectUri } = response.result;
console.log('State:', state);
console.log('Code Verifier:', codeVerifier);
console.log('Nonce:', nonce);
console.log('Redirect URI:', redirectUri);
break;
case 204:
// No artifacts yet - user hasn't authorized
console.log('No authorization artifacts found');
break;
}
} else if (isErrorResponse(response)) {
console.error(`Error ${response.status_code}: ${response.error}`);
} else {
console.error('Unhandled response');
}
JSBridge module for authenticating users via GrabID.
Remarks
Handles OAuth2/OIDC authentication flows with PKCE support, enabling MiniApps to obtain user identity tokens. Supports both native in-app consent and web-based fallback flows. This code must run on the Grab SuperApp's WebView to function correctly.
Example
ES Module:
Example
CDN (UMD):