SSO Mini App SDK

PKCE-based SSO client for Revolut mini apps. The SDK redirects to the SSO server with an app-link challenge, receives an auth code via redirect callback, and exposes the PKCE codeVerifier so the backend can exchange the code for tokens.

Table of Contents

• Install
• Instantiate client
• Update options
• Authenticate with app link
• Redirect callback

Install

npm install @revolut/sso-miniapp-sdk

Instantiate client

import { RevolutSsoClient } from '@revolut/sso-miniapp-sdk'

const ssoClient = new RevolutSsoClient({
  clientId: 'YOUR_CLIENT_ID',
  mode: 'production', // Required. One of: sandbox' | 'production'
  // locale: 'en',          // Optional. SSO UI locale
  // colorScheme: 'auto',   // Optional. 'light' | 'dark' | 'auto'
  // uiBackground: 'blue',  // Optional. ui-kit-supported background for Transparent mode
})

Update options

ssoClient.updateOptions({
  // locale: 'de',
  // colorScheme: 'light',
  // uiBackground: 'blue',
})

clientId and mode are fixed for the lifetime of the client and cannot be updated.

Authenticate with app link

The mini app receives an appLinkId from the host (Revolut mobile app). Calling authWithAppLink generates a PKCE pair, stores the code verifier, and redirects the browser to the SSO challenge URL. After the challenge is verified, SSO redirects back to redirectUri with code and state query parameters.

ssoClient.authWithAppLink({
  appLinkId: 'YOUR_APP_LINK_ID', // Provided by the host mobile app
  redirectUri: 'CALLBACK_URL',
  // replace: false,                            // Optional. Use window.location.replace instead of assign
  // locale: 'en',                              // Optional. Overrides client locale
  // colorScheme: 'light',                      // Optional. Overrides client colorScheme
  // uiBackground: 'blue',                      // Optional. Overrides client uiBackground
  // extraParams: { app_state: 'foo' },         // Optional. Additional query parameters
})

See Redirect callback for handling the response.

Redirect callback

RevolutSsoClient provides three static methods to read the callback parameters:

• processRedirectCallback() — calls readRedirectParams() and then clearRedirectParams(). Use this by default.
• readRedirectParams() — returns code + codeVerifier, or error + errorDescription, without modifying the URL.
• clearRedirectParams() — removes code, state, error, error_description from the URL and deletes the stored codeVerifier for the returned state.

Return value is one of:

• SuccessResult — { status: 'success', authCode, codeVerifier }
• ErrorResult — { status: 'error', error, errorDescription? }
• null — no relevant parameters in the URL

import { RevolutSsoClient } from '@revolut/sso-miniapp-sdk'

const result = RevolutSsoClient.processRedirectCallback()

if (result === null) {
  // No callback parameters in the URL
  return
}

if (result.status === 'error') {
  reportError({
    error: result.error,
    description: result.errorDescription,
  })
  return
}

// Exchange code + codeVerifier at your backend for tokens
await fetch('/api/sso/exchange', {
  method: 'POST',
  body: JSON.stringify({
    code: result.authCode,
    codeVerifier: result.codeVerifier,
  }),
})

Possible error values from readRedirectParams

In addition to server-provided OAuth errors (e.g. access_denied) the SDK can return:

• code_verifier_not_found — code and state are in the URL, but no stored verifier matches the state (e.g. localStorage / cookies were cleared between redirect and callback).
• state_not_found — code is in the URL but state is missing entirely.

Back to top