@revolut/revolut-id

Revolut ID SDK for web applications - Secure authentication and identity verification powered by Revolut.

Installation

npm install @revolut/revolut-id

yarn add @revolut/revolut-id

pnpm add @revolut/revolut-id

Usage

Loading script and basic setup

Popup Mode (requires callbacks)

import { RevolutIdLoader } from '@revolut/revolut-id'

RevolutIdLoader().then((revolutId) => {
  revolutId
    .initialise({
      clientId: 'your-client-id',
      redirectUri: 'https://your-app.com/callback',
      scope: ['name', 'email', 'address'], // openid scope is included by default and can be skipped
      displayMode: 'popup',
      onAuthSuccess: (result) => {
        console.log('Auth success:', result.code)
        // Handle successful authentication
      },
      onAuthFailure: (error) => {
        console.error('Auth failed:', error.error)
        // Handle authentication failure
      },
    })
    .mountButton(document.getElementById('revolut-button-container'))
})

Redirect Mode (default)

import { RevolutIdLoader } from '@revolut/revolut-id'

RevolutIdLoader().then((revolutId) => {
  revolutId
    .initialise({
      clientId: 'your-client-id',
      redirectUri: 'https://your-app.com/callback',
      scope: ['name', 'email', 'address'], // openid scope is included by default and can be skipped
      // displayMode: 'redirect' is optional (default)
    })
    .mountButton(document.getElementById('revolut-button-container'))
})

Configuration Options

RevolutIdLoader Parameters

• mode (optional): 'production' | 'sandbox' - Environment to use (defaults to 'production')

Initialization Parameters

Base Configuration (required for all modes):

• clientId: Your Revolut application client ID
• redirectUri: URI to redirect to after authentication
• scope: Array of requested permissions ('openid', 'profile', 'name', 'email', 'phone')

Optional Configuration:

• displayMode: 'popup' | 'redirect' - Authentication flow type (defaults to 'redirect')
• colorScheme: 'light' | 'dark' | 'auto' - UI theme
• countryCodes: Array of allowed country codes (as strings)
• locale: Language/locale code
• mode: 'production' | 'sandbox' - Environment mode

Popup Mode Specific (required when displayMode: 'popup'):

• onAuthSuccess: Callback for successful authentication
• onAuthFailure (optional): Callback for authentication errors

Button Styling Options

• kind: 'continue' | 'sign_in' | 'sign_up' | 'verify' | 'icon'
• size: 'large' | 'small'
• variant: 'dark' | 'light' | 'light-outlined'
• radius: 'none' | 'default' | 'round'

UX Modes

The SDK supports two authentication flows:

Popup Mode (displayMode: 'popup')

• Opens authentication in a popup window
• User stays on the original page
• Requires onAuthSuccess callback (and optionally onAuthFailure)
• Results are handled via callbacks

Redirect Mode (displayMode: 'redirect' or default)

• Redirects the user to Revolut's authentication page
• User is redirected back to your redirectUri after authentication
• No callbacks required in configuration
• Use processRedirectParams() to handle the result

Handling Authentication Flow

For Redirect Mode

// Handle redirect callback (on your redirect URI page)
const result = revolutId.processRedirectParams()

if (result?.status === 'success') {
  // Exchange authorization code for tokens
  const { code, codeVerifier } = result
  // Send to your backend to exchange for access token
} else if (result?.status === 'error') {
  console.error('Authentication error:', result.error)
}

For Popup Mode

Results are handled automatically via the onAuthSuccess and onAuthFailure callbacks provided in the configuration.

TypeScript Support

Full TypeScript definitions are included:

import RevolutIdLoader, {
  RevolutId,
  Config,
  SuccessResult,
  ErrorResult,
  ButtonStyle,
  ButtonClient,
  Mode,
  CountryCode,
  Local,
  ErrorType,
  OpenIdScope,
  ColorScheme,
} from '@revolut/revolut-id'

Examples

Custom Button Styling

const client = revolutId.initialise({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  scope: ['profile'],
  displayMode: 'popup',
  onAuthSuccess: handleSuccess,
  colorScheme: 'dark',
})

client.mountButton(buttonContainer, {
  kind: 'sign_up',
  size: 'large',
  variant: 'light-outlined',
  radius: 'round',
})

Error Handling

const client = revolutId.initialise({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  scope: ['profile'],
  displayMode: 'popup',
  onAuthSuccess: handleSuccess,
  onAuthFailure: (error) => {
    switch (error.error) {
      case 'user_cancelled':
        console.log('User cancelled authentication')
        break
      case 'access_denied':
        console.log('Access denied')
        break
      case 'popup_blocked':
        console.log('Opening popup is blocked')
        break
      default:
        console.error('Authentication error:', error.errorDescription)
    }
  },
})

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, guidelines, and workflow information.

License

Apache-2.0

© 2025 Revolut Ltd