# Integrate SDK

Revolut ID Web SDK is available for integration as the [@revolut/revolut-id](https://www.npmjs.com/package/@revolut/revolut-id) NPM package with full TypeScript support or as simple CDN script. Choose your preferred installation method:

### NPM package

```install
npm install @revolut/revolut-id
```

### or CDN script

```html
<!-- Sandbox -->
<script src="https://sandbox-sso.revolut.com/static/js/revolut-id-sdk.js"></script>

<!-- Production -->
<script src="https://sso.revolut.com/static/js/revolut-id-sdk.js"></script>
```

## Integration

### HTML container

Specify on your HTML page container for mounting Revolut ID button

```html
<div id="revolut-id-button-container"></div>
```

### Initialisation and mounting

Initialisation configuration and processing auth callback depends on selected display mode `popup` or `redirect`.

- ![Popup display mode]

  Authentication opens in a popup window, user stays on the original page.

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

  const revolutId = await RevolutIdLoader({ mode: 'production' }) // mode is optional, defaults to 'production'; use 'sandbox' for testing

  const { mountButton } = revolutId.initialise({
    clientId: 'your-client-id',
    redirectUri: 'https://your-app.com/callback',
    scope: ['profile'], // 'openid' scope is included by default
    displayMode: 'popup',
    onAuthSuccess: ({ code, codeVerifier }) => {
      // Send to backend for token exchange
      console.log('Success:', { code, codeVerifier })
    },
  })

  const container = document.getElementById('revolut-id-button-container')

  const buttonClient = mountButton(container, {
    kind: 'sign_up',
    size: 'large',
    variant: 'light-outlined',
    radius: 'round',
  })
  ```

- ![Redirect display mode]

  User is redirected to Revolut authentication page, then back to your redirect URI.

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

  const revolutId = await RevolutIdLoader({ mode: 'production' })

  const { mountButton } = revolutId.initialise({
    clientId: 'your-client-id',
    redirectUri: 'https://your-app.com/callback',
    scope: ['profile'], // 'openid' scope is included by default
  })

  const container = document.getElementById('revolut-id-button-container')

  const buttonClient = mountButton(container, {
    kind: 'sign_up',
    size: 'large',
    variant: 'light-outlined',
    radius: 'round',
  })
  ```

  **On your `redirect_uri` page**

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

  const revolutId = await RevolutIdLoader({ mode: 'production' })

  const result = revolutId.processRedirectParams()

  if (result?.status === 'success') {
    const { code, codeVerifier } = result
    // Send to backend for token exchange
  }
  ```

:::info
If you're using the CDN script, `window.revolut.revolutId` will be available globally and you can use it directly without importing `RevolutIdLoader`.
:::

### Unmounting

Unmount button if needed.

```typescript
buttonClient.unmount()
```


### API reference

The Revolut ID Web SDK provides the `RevolutId` interface, which is returned by `RevolutIdLoader` (NPM installation) or available in the global window scope via `window.revolut.revolutId` (CDN script).

```typescript
export interface ButtonClient {
  mount: (container: HTMLElement, params?: ButtonStyle) => ButtonClient
  unmount: () => void
}

export interface RevolutId {
  initialise: (config: Config) => {
    mountButton: (container: HTMLElement, params?: ButtonStyle) => ButtonClient
  }

  processRedirectParams: () => SuccessResult | ErrorResult | null
}
```

#### Config - initialisation parameters (required)

| Parameter       | Type                                                                                   | Description                                                     | Required                      |
| --------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------- |
| `clientId`      | `string`                                                                               | Your Revolut application client ID                              | Yes                           |
| `redirectUri`   | `string`                                                                               | URI to redirect to after authentication                         | Yes                           |
| `scope`         | `OpenIdScope[]`                                                                        | Array of requested OpenID scopes (`openid` included by default) | Yes                           |
| `displayMode`   | <code>popup \| redirect</code>                                                         | Authentication display mode                                     | No (defaults to `redirect`)   |
| `mode`          | <code>production \| sandbox</code>                                                     | Environment mode                                                | No (defaults to 'production') |
| `uiColorScheme` | <code>light \| dark \| system</code>                                                   | UI theme preference                                             | No                            |
| `uiBackground`  | <code>blue \| deep-blue \| green \| orange \| teal \| purple \| holo \| minimal</code> | Authentication page background                                  | No                            |
| `countryCodes`  | `string[]`                                                                             | Array of allowed country codes                                  | No                            |
| `locale`        | `string`                                                                               | Language/locale code                                            | No                            |
| `onAuthSuccess` | `(result: SuccessResult) => void`                                                      | Success callback function                                       | Yes (popup mode only)         |
| `onAuthFailure` | `(result: ErrorResult) => void`                                                        | Error callback function                                         | No (popup mode only)          |

For complete configuration documentation and advanced options, see [Config API reference](/docs/sdks/revolut-id-sdk/web/api-reference/revolut-id#config-parameters).

#### ButtonStyle - button styling parameters (optional)

| Parameter | Type                                                          | Description             | Default               | Required |
| --------- | ------------------------------------------------------------- | ----------------------- | --------------------- | -------- |
| `kind`    | <code>continue \| sign_in \| sign_up \| verify \| icon</code> | Button text and purpose | <code>sign_in</code>  | No       |
| `size`    | <code>large \| small</code>                                   | Button size             | <code>large</code>    | No       |
| `variant` | <code>dark \| light \| light-outlined</code>                  | Visual style            | <code>dark</code>     | No       |
| `radius`  | <code>none \| default \| round</code>                         | Corner rounding         | <code>default</code>  | No       |

For complete button styling documentation and usage examples, see [ButtonStyle API reference](/docs/sdks/revolut-id-sdk/web/api-reference/button-style).

:::tip[Environment setup]
The environment you use **must** match your client environment configuration.

- Use `production` mode with your production client ID for live applications
- Use `sandbox` mode with your sandbox client ID for development and testing

See [environment configuration](/docs/sdks/revolut-id-sdk/web/configure-client#environment-configuration) for more details.
:::

## Next steps

Learn how to exchange code for user ID token - [code exchange](/docs/sdks/revolut-id-sdk/web/code-exchange).