# Integrate the Revolut ID SDK for iOS

This guide walks you through the complete setup required to authenticate users with their Revolut account from your iOS app.

:::info
For a complete working example, see the [Example project](https://bitbucket.org/revolut/revolut-id-ios) included with the SDK.
:::

## How it works

The Revolut ID SDK uses an OAuth 2.0 PKCE flow with the following components:

- **iOS app:** The Revolut ID SDK generates a PKCE code pair, opens the Revolut app (or web app if not installed) for the user to sign in and grant permissions, then returns an authorisation code and code verifier.
- **Your backend:** Exchanges the code and code verifier at Revolut's token endpoint to obtain an access token with the permitted user details.

The integration flow works as follows:

1. Your app calls `authorise(scope:completion:)` — the SDK opens the Revolut app or web app for the user to authenticate and grant permissions.
1. After the user signs in, Revolut redirects back to your app with an authorisation code via the custom URL scheme.
1. Your app passes the code and code verifier to your backend.
1. Your backend exchanges them at Revolut's token endpoint to receive an access token with the permitted user details.

### Implementation overview

1. [Install the SDK](#1-install-the-sdk)
1. [Declare the Revolut URL scheme](#2-declare-the-revolut-url-scheme)
1. [Configure the SDK](#3-configure-the-sdk)
1. [Allowlist the redirect URI](#4-allowlist-the-redirect-uri)
1. [Add a sign-in button](#5-add-a-sign-in-button)
1. [Trigger authorisation](#6-trigger-authorisation)
1. [Handle the redirect URL](#7-handle-the-redirect-url)
1. [Test with the sandbox environment](#8-test-with-the-sandbox-environment)

### Before you begin

- [ ] iOS 15.0 or later
- [ ] A Revolut business account with an OAuth client configured in the [Revolut APIs settings](https://business.revolut.com/settings/apis)

## Integrate the SDK

### 1. Install the SDK

#### Swift Package Manager

1. In Xcode, open **File → Add Package Dependencies…**

1. Enter the repository URL:

   ```text
   https://bitbucket.org/revolut/revolut-id-ios
   ```

1. Set the dependency rule to **Up to Next Major Version** from `0.1.0`.

1. Click **Add Package**.

1. Select the **RevolutId** product and add it to your target.

1. Select the project in the Navigator → your target in the left column → **Build phases**

1. Make sure **RevolutId** is listed under **Link Binary With Libraries** phase. If it isn't, click + inside that phase, find **RevolutId** under Packages, and click Add.

1. Add a new **Run Script** phase in **Build Phases** with the following content:

   ```sh
   sh ${BUILD_DIR%Build/*}SourcePackages/checkouts/revolut-id-ios/Scripts/install_bundles.sh
   ```

#### Manual installation

1. Drag and drop `RevolutId.xcframework` into your Xcode project.

1. In the target's **General** tab, set the framework to **Embed Without Signing**.

1. Drag and drop the resource bundles from the `Releases` directory into your project.

### 2. Declare the Revolut URL scheme

The SDK opens the Revolut app (if installed) or the Revolut web app when you call `authorise`. iOS requires apps to declare any URL schemes they intend to query.

Add the following to your `Info.plist`:

```xml
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>revolut</string>
</array>
```

### 3. Configure the SDK

#### Add your client ID

Add your Revolut client ID to `Info.plist` under the `RevolutClientID` key:

```xml
<key>RevolutClientID</key>
<string>{YOUR_CLIENT_ID}</string>
```

:::info
Use `RevolutClientID-Sandbox` key for your sandbox client ID.
:::

#### Register the redirect URL scheme

Register a custom URL scheme so that the Revolut app can redirect back to your app after authorisation. The scheme must use the `rev` prefix followed by your client ID:

```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>rev{YOUR_CLIENT_ID}</string>
        </array>
    </dict>
</array>
```

#### Initialise the SDK on launch

Import the module and call `RevolutIdKit.configure(with:)` in your `AppDelegate` before any other SDK usage:

```swift

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        RevolutIdKit.configure(
            with: RevolutIdKit.Configuration(
                environment: .production
            )
        )
        return true
    }
}
```

### 4. Allowlist the redirect URI

Revolut only redirects to URIs that have been explicitly authorised for your OAuth client. Add the mobile redirect URI before testing:

1. Go to the **Revolut ID API** tab on the [APIs settings page](https://business.revolut.com/settings/apis).
1. Open your OAuth client.
1. In **Authorized redirect URIs**, add:

   ```text
   rev{YOUR_CLIENT_ID}://merchant-permissions
   ```

### 5. Add a sign-in button

The SDK provides a Revolut logo image you can use to build a branded sign-in button:

```swift
let button = UIButton()
button.setImage(
    RevolutIdKit.shared.revolutLogoIcon24,
    for: .normal
)
```

### 6. Trigger authorisation

Call `authorise(scope:completion:)` when the user taps the sign-in button. Pass the scopes your app requires — available values are listed in `scopes_supported` at the [OpenID configuration endpoint](https://sso.revolut.com/.well-known/openid-configuration).

```swift
RevolutIdKit.shared.authorise(
    scope: ["name", "email"]
) { result in
    switch result {
    case let .success(credentials):
        // Pass credentials.code and credentials.codeVerifier to your backend
        // to exchange for an access token.
        print("code: \(credentials.code)")
        print("codeVerifier: \(credentials.codeVerifier)")
    case let .failure(reason):
        print("Authorisation failed: \(reason)")
    case .cancelled:
        print("Authorisation cancelled by user")
    }
}
```

On success, send `code` and `codeVerifier` to your backend. Your backend exchanges these with Revolut's token endpoint (`token_endpoint` in the [OpenID configuration](https://sso.revolut.com/.well-known/openid-configuration)) to obtain an access token with the permitted user details.

### 7. Handle the redirect URL

After authorisation, Revolut redirects the user back to your app via the custom URL scheme. Pass the incoming URL to the SDK so it can extract the authorisation response.

- ![SceneDelegate]

```swift
class SceneDelegate: UIResponder, UIWindowSceneDelegate, UISceneDelegate {

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        for context in URLContexts {
            _ = RevolutIdKit.shared.handle(url: context.url)
        }
    }
}
```

- ![AppDelegate]

```swift
@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
        return RevolutIdKit.shared.handle(url: url)
    }
}
```

### 8. Test with the sandbox environment

Use the `.sandbox` environment to test without affecting production data. In sandbox mode, Revolut redirects users to the Revolut web app because the Revolut mobile app does not support sandbox.

```swift
RevolutIdKit.configure(
    with: RevolutIdKit.Configuration(
        environment: .sandbox
    )
)
```

The sandbox OpenID configuration is available at [https://sandbox-sso.revolut.com/.well-known/openid-configuration](https://sandbox-sso.revolut.com/.well-known/openid-configuration).

:::note
Ensure you switch back to `.production` before releasing your app.
:::

## Implementation checklist

- [ ] SDK installed via Swift Package Manager or added as `RevolutId.xcframework`
- [ ] `revolut` added to `LSApplicationQueriesSchemes` in `Info.plist`
- [ ] Client ID added to `Info.plist` under `RevolutClientID`
- [ ] Sandbox client ID added to `Info.plist` under `RevolutClientID-Sandbox` (for sandbox testing)
- [ ] Redirect URL scheme `rev{YOUR_CLIENT_ID}` registered in `Info.plist`
- [ ] `RevolutIdKit.configure(with:)` called on app launch
- [ ] Redirect URI added to your OAuth client's authorised URIs
- [ ] Sign-in button wired to `RevolutIdKit.shared.authorise(scope:completion:)`
- [ ] Redirect URL handled in `SceneDelegate` or `AppDelegate`

## What's next

- [Code exchange](./code-exchange) — exchange the authorisation code and code verifier for an access token on your backend
- [Methods and parameters](./api-reference) — full reference for all `RevolutIdKit` types and methods