# RemoteAuthClient

Artifact: [androidx.wear:wear-phone-interactions](https://developer.android.com/jetpack/androidx/releases/wear) [View Source](https://cs.android.com/search?q=file:androidx/wear/phone/interactions/authentication/RemoteAuthClient.kt+class:androidx.wear.phone.interactions.authentication.RemoteAuthClient) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear#1.0.0)

*** ** * ** ***


```
class RemoteAuthClient : AutoCloseable
```

<br />

*** ** * ** ***

Provides a client for supporting remote authentication on Wear. The authentication session will be opened on the user's paired phone.

- The following example triggers an authorization session to open on the phone.

```kotlin
// PKCE (Proof Key for Code Exchange) is required for the auth
private var codeVerifier: CodeVerifier
// Late initialization in place where it's used, or to be initialized in onCreate()
private var lateinit authClient: RemoteAuthClient

override public fun onDestroy() {
  authClient.close();
  super.onDestroy();
}

public fun startAuthFlow() {
   // PKCE (Proof Key for Code Exchange) is required, store this code verifier here .
   // To access the resource later, both the auth token and code verifier are needed.
   codeVerifier = CodeVerifier()

  // Construct your auth request.
  authClient = RemoteAuthClient.create(this);
  authClient.sendAuthorizationRequest(
     OAuthRequest.Builder(this.applicationContext)
         .setAuthProviderUrl(Uri.parse("https://...."))
         .setCodeChallenge(CodeChallenge(codeVerifier))
         .build(),
     Executors.newSingleThreadExecutor(),
     new MyAuthCallback()
  );
}

private  class MyAuthCallback: RemoteAuthClient.Callback {
  override public fun onAuthorizationResponse(
     request: OAuthRequest,
     response: OAuthResponse
   ) {
    // Parse the result token out of the response and store it, e.g. in SharedPreferences,
    // so you can use it later (Note, use together with code verifier from version R)
    // You'll also want to display a success UI.
    ...
  }

  override fun onAuthorizationError(request: OAuthRequest, errorCode: Int) {
    // Compare against codes available in RemoteAuthClient.ErrorCode
    // You'll also want to display an error UI.
    ...
  }
}
```

## Summary

| ### Nested types |
|---|
| `abstract class https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient.Callback` This callback is notified when an async remote authentication request completes. |

| ### Constants |
|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#ERROR_PHONE_UNAVAILABLE() = 1` Indicates no phone is connected, or the phone connected doesn't support 3p auth |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#ERROR_UNSUPPORTED() = 0` Indicates 3p authentication isn't supported by Wear OS |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#NO_ERROR()` Indicates 3p authentication is finished without error |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_AVAILABLE() = 3` Indicates that remote auth is available with a connected device capable to handle the remote interaction. |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_TEMPORARILY_UNAVAILABLE() = 2` Indicates that remote auth is temporarily unavailable. |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_UNAVAILABLE() = 1` Indicates that remote auth is unavailable because there is no paired device capable of handling the remote interaction. |
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_UNKNOWN() = 0` The remote auth's availability is unknown. |

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#create(android.content.Context)(context: https://developer.android.com/reference/android/content/Context.html)` Return a client that can be used to make async remote authorization requests |

| ### Public functions |
|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/UiThread https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#close()()` Frees any resources used by the client, dropping any outstanding requests. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/UiThread https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#sendAuthorizationRequest(androidx.wear.phone.interactions.authentication.OAuthRequest,java.util.concurrent.Executor,androidx.wear.phone.interactions.authentication.RemoteAuthClient.Callback)( request: https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/OAuthRequest, executor: https://developer.android.com/reference/java/util/concurrent/Executor.html, clientCallback: https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient.Callback )` Send a remote auth request. |

| ### Protected functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#finalize()()` Check that the explicit termination method 'close' is called |

| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>` | `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#availabilityStatus()` Returns status indicating whether remote auth operation (such as `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#sendAuthorizationRequest(androidx.wear.phone.interactions.authentication.OAuthRequest,java.util.concurrent.Executor,androidx.wear.phone.interactions.authentication.RemoteAuthClient.Callback)`) is available. |

## Constants

### ERROR_PHONE_UNAVAILABLE

```
const val ERROR_PHONE_UNAVAILABLE = 1: Int
```

Indicates no phone is connected, or the phone connected doesn't support 3p auth

### ERROR_UNSUPPORTED

```
const val ERROR_UNSUPPORTED = 0: Int
```

Indicates 3p authentication isn't supported by Wear OS

### NO_ERROR

```
const val NO_ERROR: Int
```

Indicates 3p authentication is finished without error

### STATUS_AVAILABLE

```
const val STATUS_AVAILABLE = 3: Int
```

Indicates that remote auth is available with a connected device capable to handle the remote interaction.

### STATUS_TEMPORARILY_UNAVAILABLE

```
const val STATUS_TEMPORARILY_UNAVAILABLE = 2: Int
```

Indicates that remote auth is temporarily unavailable.

There is a known paired device, but it is not currently connected or reachable to handle the remote interaction.

### STATUS_UNAVAILABLE

```
const val STATUS_UNAVAILABLE = 1: Int
```

Indicates that remote auth is unavailable because there is no paired device capable of handling the remote interaction.

### STATUS_UNKNOWN

```
const val STATUS_UNKNOWN = 0: Int
```

The remote auth's availability is unknown.

On older devices, `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_UNKNOWN()` is returned as we can not determine the availability states. To preserve compatibility with existing devices behavior, try `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#sendAuthorizationRequest(androidx.wear.phone.interactions.authentication.OAuthRequest,java.util.concurrent.Executor,androidx.wear.phone.interactions.authentication.RemoteAuthClient.Callback)` and handle error codes accordingly.

## Public companion functions

### create

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear#1.0.0)

```
fun create(context: Context): RemoteAuthClient
```

Return a client that can be used to make async remote authorization requests

## Public functions

### close

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear#1.0.0)

```
@UiThread
open fun close(): Unit
```

Frees any resources used by the client, dropping any outstanding requests. The client cannot be used to make requests thereafter.

### sendAuthorizationRequest

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear#1.0.0)

```
@UiThread
fun sendAuthorizationRequest(
    request: OAuthRequest,
    executor: Executor,
    clientCallback: RemoteAuthClient.Callback
): Unit
```

Send a remote auth request. This will cause an authorization UI to be presented on the user's phone. This request is asynchronous; the callback provided will be be notified when the request completes.

| Parameters |
|---|---|
| `request: https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/OAuthRequest` | Request that will be sent to the phone. The auth response should redirect to the Wear OS companion. See `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/OAuthRequest#WEAR_REDIRECT_URL_PREFIX()` |
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | The executor that callback will called on. |
| `clientCallback: https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient.Callback` | The callback that will be notified when request is completed. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-runtime-exception/index.html` | if the service has error to open the request |

## Protected functions

### finalize

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/wear#1.0.0)

```
protected fun finalize(): Unit
```

Check that the explicit termination method 'close' is called

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-runtime-exception/index.html` | if the 'close' method was not called |

## Public properties

### availabilityStatus

Added in [1.1.1](https://developer.android.com/jetpack/androidx/releases/wear#1.1.1)

```
val availabilityStatus: Flow<Int>
```

Returns status indicating whether remote auth operation (such as `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#sendAuthorizationRequest(androidx.wear.phone.interactions.authentication.OAuthRequest,java.util.concurrent.Executor,androidx.wear.phone.interactions.authentication.RemoteAuthClient.Callback)`) is available.

In scenarios of restricted connection or temporary disconnection with a paired device, remote auth operations will not be available. Please check status before `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#sendAuthorizationRequest(androidx.wear.phone.interactions.authentication.OAuthRequest,java.util.concurrent.Executor,androidx.wear.phone.interactions.authentication.RemoteAuthClient.Callback)` to provide better experience for the user.

On older wear devices which do not support availability status, it will always return `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_UNKNOWN()`. Wear devices start to support determining the availability status from Wear Sdk WEAR_TIRAMISU_4.

```kotlin
import androidx.wear.phone.interactions.authentication.RemoteAuthClient

remoteAuthClient.availabilityStatus.collect { status ->
    when (status) {
        RemoteAuthClient.STATUS_UNAVAILABLE ->
            TODO("Present alternative flow as remote auth is not available")
        RemoteAuthClient.STATUS_TEMPORARILY_UNAVAILABLE ->
            TODO("Present education to user to connect devices or bring to proximity.")
        RemoteAuthClient.STATUS_AVAILABLE,
        RemoteAuthClient.STATUS_UNKNOWN ->
            // Present normal auth flow when we don't know (old devices)
            // or when we know it is available.
            remoteAuthClient.sendAuthorizationRequest(
                oAuthRequest,
                Runnable::run,
                myAuthCallback
            )
    }
}
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>` | a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` with a stream of status updates that could be one of `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_UNKNOWN()`, `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_UNAVAILABLE()`, `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_TEMPORARILY_UNAVAILABLE()`, `https://developer.android.com/reference/kotlin/androidx/wear/phone/interactions/authentication/RemoteAuthClient#STATUS_AVAILABLE()`. |