# Revolut ID Android SDK

Reference for the parameters, objects, and types available in the Revolut ID Android SDK.

:::info
For detailed instructions on how to install and integrate the SDK, see: [Revolut ID SDK for Android: Integration guide](/docs/sdks/revolut-id-sdk/android/integration-guide).
:::

## Methods and parameters

### `RevolutIdAuthenticator.create` factory

Creates and returns a `RevolutIdAuthenticator` instance. Create it once and reuse it throughout your app's session.

```kotlin

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

| Parameter   | Description                                              | Format                                           | Required   |
| ----------- | -------------------------------------------------------- | ------------------------------------------------ | ---------- |
| `config`    | The SDK configuration specifying the target environment. | [`RevolutIdConfig`](#revolutidconfig-data-class) | Yes        |
| `context`   | Android application context.                             | `Context`                                        | Yes        |

### `RevolutIdAuthenticator.authorise` method

Launches the Revolut authorisation flow and returns a [`RevolutIdAuthoriseResult`](#revolutidauthoriseresult-sealed-interface) indicating whether the flow was started. The launch target depends on the configured [`RevolutIdEnvironment`](#revolutidenvironment-enumeration).

```kotlin
fun authorise(
    clientId: String,
    scopes: String,
    redirectUri: Uri,
    state: String,
): RevolutIdAuthoriseResult
```

| Parameter     | Description                                                                                                                                                                                          | Format   | Required   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------- |
| `clientId`    | Your OAuth client ID issued by Revolut.                                                                                                                                                              | `String` | Yes        |
| `scopes`      | Space-separated list of OAuth scopes to request. Available scopes are listed in `scopes_supported` at the [OpenID configuration endpoint](https://sso.revolut.com/.well-known/openid-configuration). | `String` | Yes        |
| `redirectUri` | The URI the user is redirected to after authorisation. Must match a URI allowlisted in your OAuth client settings.                                                                                   | `Uri`    | Yes        |
| `state`       | Cryptographically random string generated per request. The app must verify it matches the value returned in the redirect to prevent CSRF attacks.                                                    | `String` | Yes        |

**Returns:** [`RevolutIdAuthoriseResult`](#revolutidauthoriseresult-sealed-interface) — `Success` if the authorisation flow was launched, otherwise an `Error` describing why it could not be started.

### `RevolutIdAuthenticator.handle` method

Processes the redirect URI received when the user returns to your app after authorisation. Returns a [`RevolutIdHandleResult`](#revolutidhandleresult-sealed-interface) representing the outcome of the flow.

Call this in both `onCreate` and `onNewIntent` of the Activity registered with the `<intent-filter>` matching your `redirectUri`. See [Declare the redirect URI](/docs/sdks/revolut-id-sdk/android/integration-guide#2-declare-the-redirect-uri) for the manifest setup.

```kotlin
fun handle(uri: Uri): RevolutIdHandleResult
```

| Parameter   | Description                                                | Format   | Required   |
| ----------- | ---------------------------------------------------------- | -------- | ---------- |
| `uri`       | The URI received from the redirect intent (`intent.data`). | `Uri`    | Yes        |

## Helper objects and types

### `RevolutIdConfig` data class

Configuration passed to `RevolutIdAuthenticator.create`. Specifies the target Revolut environment.

```kotlin
data class RevolutIdConfig(
    val environment: RevolutIdEnvironment,
)
```

| Parameter     | Description                          | Format                                                      | Required   |
| ------------- | ------------------------------------ | ----------------------------------------------------------- | ---------- |
| `environment` | The environment the SDK operates in. | [`RevolutIdEnvironment`](#revolutidenvironment-enumeration) | Yes        |

### `RevolutIdEnvironment` enumeration

Specifies whether the SDK targets the production or sandbox Revolut environment.

```kotlin
enum class RevolutIdEnvironment {
    RELEASE,
    SANDBOX,
}
```

| Case      | Description                                                                                                                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RELEASE` | For live use. Launches the Revolut app if installed, or falls back to `https://sso.revolut.com`. Must be paired with a production client ID.                                                            |
| `SANDBOX` | For development and testing. Always opens a browser pointing to `https://sandbox-sso.revolut.com`. Must be paired with a sandbox client ID. Note: the Revolut mobile app does not support sandbox mode. |

:::info
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).
:::

## Drawable resources

The SDK bundles two Revolut logo drawables for building a branded sign-in button.

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

Reference them in your XML layout:

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

## Callbacks and results

### `RevolutIdAuthoriseResult` sealed interface

Returned by `RevolutIdAuthenticator.authorise()`. Indicates whether the SDK successfully launched the authorisation flow.

```kotlin
sealed interface RevolutIdAuthoriseResult {
    data object Success : RevolutIdAuthoriseResult

    sealed interface Error : RevolutIdAuthoriseResult {
        data class InvalidParameters(val message: String) : Error
        data object RequestHandlerNotFound : Error
    }
}
```

| Case      | Description                                                                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Success` | The authorisation flow was successfully initiated. Wait for the redirect in your callback Activity.                                                           |
| `Error`   | The authorisation flow could not be started. See [`RevolutIdAuthoriseResult.Error`](#revolutidauthoriseresulterror-sealed-interface) for the available cases. |

### `RevolutIdHandleResult` sealed interface

Returned by `RevolutIdAuthenticator.handle()`. Represents the final outcome of the authorisation flow.

```kotlin
sealed interface RevolutIdHandleResult {
    data class Success(
        val code: String,
        val codeVerifier: String,
    ) : RevolutIdHandleResult

    object Cancelled : RevolutIdHandleResult

    sealed interface Error : RevolutIdHandleResult {
        sealed interface AuthorisationFailed : Error {
            object AuthorisationNotAvailable : AuthorisationFailed
            object Timeout : AuthorisationFailed
            object Interrupted : AuthorisationFailed
            data class Unknown(val details: String?) : AuthorisationFailed
        }
        object CodeVerifierIsEmpty : Error
    }
}
```

| Case        | Description                                                                                                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Success`   | Authorisation succeeded. The associated [`Success`](#revolutidhandleresultsuccess-data-class) value contains the `code` and `codeVerifier` needed for backend token exchange. |
| `Cancelled` | The user dismissed the authorisation flow without completing it.                                                                                                              |

### `RevolutIdHandleResult.Success` data class

Contains the values your backend requires to exchange for an access token via the [token endpoint](https://sso.revolut.com/.well-known/openid-configuration).

| Property       | Description                                                                                                         | Format   |
| -------------- | ------------------------------------------------------------------------------------------------------------------- | -------- |
| `code`         | The authorisation code received from Revolut.                                                                       | `String` |
| `codeVerifier` | The PKCE code verifier generated by the SDK. Must be sent alongside `code` to complete the token exchange securely. | `String` |

## Errors

### `RevolutIdAuthoriseResult.Error` sealed interface

Describes why the SDK could not launch the authorisation flow. Returned as the `Error` branch of [`RevolutIdAuthoriseResult`](#revolutidauthoriseresult-sealed-interface).

| Case                           | Description                                                                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Error.InvalidParameters`      | One or more parameters provided to `authorise()` were invalid. The `message` property describes which parameter failed validation. |
| `Error.RequestHandlerNotFound` | The SDK could not find a Revolut application or browser to handle the authorisation request.                                       |

### `RevolutIdHandleResult.Error` sealed interface

Describes why an authorisation flow ended in failure. Returned as the `Error` branch of [`RevolutIdHandleResult`](#revolutidhandleresult-sealed-interface).

| Case                                                  | Description                                                                                                     |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Error.AuthorisationFailed.AuthorisationNotAvailable` | The user is not eligible to perform authorisation (for example, they do not have a qualifying Revolut account). |
| `Error.AuthorisationFailed.Timeout`                   | The authorisation flow timed out before the user completed it.                                                  |
| `Error.AuthorisationFailed.Interrupted`               | The authorisation flow was interrupted.                                                                         |
| `Error.AuthorisationFailed.Unknown`                   | An unexpected error occurred. The optional `details` string may contain additional context for debugging.       |
| `Error.CodeVerifierIsEmpty`                           | `handle()` was called without a preceding `authorise()` call.                                                   |