# Integrate the Revolut ID SDK for Android

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

## How it works

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

- **Android app:** The Revolut ID SDK launches the Revolut app (or a browser if not installed), receives the redirect, and 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()` — the SDK opens the Revolut app or browser for the user to authenticate and grant permissions.
1. After the user signs in, Revolut redirects back to your app via the registered redirect URI.
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 redirect URI](#2-declare-the-redirect-uri)
1. [Allowlist the redirect URI](#3-allowlist-the-redirect-uri)
1. [Create the authenticator](#4-create-the-authenticator)
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

- [ ] Android API 28 (Android 9.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

Add the SDK dependency to your module's Gradle build file:

```kotlin
dependencies {
    implementation("com.revolut:revolutid:0.1.0")
}
```

### 2. Declare the redirect URI

The SDK redirects the user back to your app after authorisation via a deep link URI. Android requires that you declare an intent filter for the Activity that will receive this redirect.

Add the following to your `AndroidManifest.xml`, replacing the scheme, host, and path with your chosen redirect URI:

```xml
<activity
    android:name=".AuthCallbackActivity"
    android:exported="true"
    android:launchMode="singleTop">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="myapp"
            android:host="auth"
            android:path="/callback" />
    </intent-filter>
</activity>
```

The example above registers `myapp://auth/callback` as the redirect URI. Use any scheme and path that uniquely identifies your app.

### 3. Allowlist the redirect URI

Revolut only redirects to URIs that have been explicitly authorised for your OAuth client. Add your 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 your redirect URI — for example:

   ```text
   myapp://auth/callback
   ```

### 4. Create the authenticator

Create a `RevolutIdAuthenticator` instance once and reuse it throughout your app's session — for example in your `Application` class or via dependency injection:

```kotlin

val authenticator = RevolutIdAuthenticator.create(
    config = RevolutIdConfig(environment = RevolutIdEnvironment.RELEASE),
    context = applicationContext,
)
```

### 5. Add a sign-in button

The SDK provides Revolut logo drawables you can use to build a branded sign-in button. Choose the variant that fits your UI:

```xml
<ImageButton
    android:id="@+id/revolut_sign_in_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:src="@drawable/logo_revolut_black"
    android:contentDescription="@string/sign_in_with_revolut" />
```

| Drawable                       | Use when          |
| ------------------------------ | ----------------- |
| `@drawable/logo_revolut_black` | Light backgrounds |
| `@drawable/logo_revolut_white` | Dark backgrounds  |

### 6. Trigger authorisation

Call `authorise()` 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).

Generate a cryptographically random `state` value for each request. The app must verify it matches the `state` returned in the redirect.

`authorise()` returns a `RevolutIdAuthoriseResult` indicating whether the flow was started. Inspect the result and surface a fallback to the user if the SDK could not launch the authorisation flow.

```kotlin

when (val result = authenticator.authorise(
    clientId = "YOUR_CLIENT_ID",
    scopes = "openid profile",
    redirectUri = Uri.parse("myapp://auth/callback"),
    state = generateSecureRandomState(),
)) {
    is RevolutIdAuthoriseResult.Success -> {
        // The authorisation flow was launched. Wait for the redirect in your callback Activity.
    }
    is RevolutIdAuthoriseResult.Error.InvalidParameters -> {
        // One or more parameters were invalid. result.message describes which one.
    }
    is RevolutIdAuthoriseResult.Error.RequestHandlerNotFound -> {
        // No Revolut app or browser is available to handle the request.
    }
}
```

The SDK launches the Revolut app if it is installed, or falls back to a browser. In `SANDBOX` mode, the SDK always opens a browser pointing to `https://sandbox-sso.revolut.com`.

### 7. Handle the redirect URL

When the user completes or cancels authorisation, Revolut redirects them back to your app via the registered redirect URI. Pass the incoming URI to the SDK in both `onCreate` and `onNewIntent` of your callback Activity:

```kotlin

class AuthCallbackActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        handleIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent) {
        val uri = intent.data ?: return
        when (val result = authenticator.handle(uri)) {
            is RevolutIdHandleResult.Success -> {
                // Pass result.code and result.codeVerifier to your backend
                // to exchange for an access token.
            }
            is RevolutIdHandleResult.Cancelled -> {
                // User dismissed the authorisation flow.
            }
            is RevolutIdHandleResult.Error.AuthorisationFailed.AuthorisationNotAvailable -> {
                // User is not eligible for the requested permissions.
            }
            is RevolutIdHandleResult.Error.AuthorisationFailed.Timeout -> {
                // The authorisation session timed out.
            }
            is RevolutIdHandleResult.Error.AuthorisationFailed.Interrupted -> {
                // The authorisation flow was interrupted (for example, by an app switch).
            }
            is RevolutIdHandleResult.Error.AuthorisationFailed.Unknown -> {
                // An unexpected error occurred. result.details may contain additional context.
            }
            is RevolutIdHandleResult.Error.CodeVerifierIsEmpty -> {
                // handle() was called without a preceding authorise() call.
            }
        }
    }
}
```

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.

### 8. Test with the sandbox environment

Use `RevolutIdEnvironment.SANDBOX` to test without affecting production data. In sandbox mode the SDK always opens a browser pointing to `https://sandbox-sso.revolut.com` — the Revolut mobile app does not support sandbox.

```kotlin
val authenticator = RevolutIdAuthenticator.create(
    config = RevolutIdConfig(environment = RevolutIdEnvironment.SANDBOX),
    context = applicationContext,
)
```

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 `RevolutIdEnvironment.RELEASE` before publishing your app.
:::

## Implementation checklist

- [ ] SDK dependency added to your Gradle build file
- [ ] Redirect URI intent filter declared in `AndroidManifest.xml`
- [ ] Redirect URI added to your OAuth client's authorised URIs
- [ ] `RevolutIdAuthenticator` created with `RevolutIdConfig`
- [ ] Sign-in button wired to `authenticator.authorise()`
- [ ] `authenticator.handle()` called in both `onCreate` and `onNewIntent`

## What's next

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