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.
This method can return the following status_code values:
200 (OK): Authorization completed successfully (native in_place flow). The result contains AuthorizeResult.204 (No Content): User cancelled the authorization flow.302 (Found): Redirect in progress (web redirect flow). The page will navigate away.400 (Bad Request): Invalid request parameters.403 (Forbidden): Client is not authorized for the requested scope.500 (Internal Server Error): Unexpected error during native authorization.501 (Not Implemented): Requires Grab app environment.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 redirectUriOn a 200 response (native in_place success), the actual redirectUri and PKCE values
(codeVerifier, nonce) are returned in response.result alongside code and state,
so you do not need to call getAuthorizationArtifacts().
For the web redirect flow (302), retrieve artifacts from getAuthorizationArtifacts() after
the redirect round-trip completes.
Consent Selection Rules (Native vs Web):
import { IdentityModule, isSuccess, isRedirection, isError } 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: {
const { code, state, codeVerifier, nonce, redirectUri } = response.result;
console.log('Auth Code:', code);
console.log('State:', state);
console.log('Code Verifier:', codeVerifier);
console.log('Nonce:', nonce);
console.log('Redirect URI:', redirectUri);
break;
}
case 204:
console.log('Authorization cancelled');
break;
}
} else if (isRedirection(response)) {
console.log('Redirecting to authorization...');
} else if (isError(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. See ClearAuthorizationArtifactsResponse.
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.
This method can return the following status_code values:
200 (OK): All artifacts present. The result contains GetAuthorizationArtifactsResult.204 (No Content): No artifacts yet - authorization has not been initiated.400 (Bad Request): Invalid request parameters.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.
import { IdentityModule, isSuccess, isError } 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 (isError(response)) {
console.error(`Error ${response.status_code}: ${response.error}`);
} else {
console.error('Unhandled response');
}
SDK module for authenticating users with GrabID via
JSBridge.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):