# One-click Auth

### Introduction <a href="#introduction" id="introduction"></a>

This section outlines an innovative protocol method that facilitates the initiation of a Sign session and the authentication of a wallet through a [Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361) (SIWE) message, enhanced by [ReCaps](https://eips.ethereum.org/EIPS/eip-5573) (ReCap Capabilities).

This enhancement not only offers immediate authentication for dApps, paving the way for prompt user logins, but also integrates informed consent for authorization. Through this mechanism, dApps can request the delegation of specific capabilities to perform actions on behalf of the wallet user. These capabilities, encapsulated within SIWE messages as ReCap URIs, detail the scope of actions authorized by the user in an explicit and human-readable form.

By incorporating ReCaps, this method extends the utility of SIWE messages, allowing dApps to combine authentication with a nuanced authorization model. This model specifies the actions a dApp is authorized to execute on the user's behalf, enhancing security and user autonomy by providing clear consent for each delegated capability. As a result, dApps can utilize these consent-backed messages to perform predetermined actions, significantly enriching the interaction between dApps, wallets, and users within the Ethereum ecosystem.

<figure><img src="https://1817686354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbrS1XyBOhxXAZTMGmUZJ%2Fuploads%2FyZBWxvky7pa9c3zcFM6Q%2Fimage.png?alt=media&#x26;token=53a37455-6539-4234-9d1e-6b0b8ff848cb" alt=""><figcaption></figcaption></figure>

### Handling Authentication Requests <a href="#handling-authentication-requests" id="handling-authentication-requests"></a>

To handle incoming authentication requests, set up StarTowerWalletKit.WalletDelegate. The onSessionAuthenticate callback will notify you of any authentication requests that need to be processed, allowing you to either approve or reject them based on your application logic.

```json
override val onSessionAuthenticate: ((Wallet.Model.SessionAuthenticate, Wallet.Model.VerifyContext) -> Unit)
  get() = { sessionAuthenticate, verifyContext ->
      // Triggered when wallet receives the session authenticate sent by a Dapp
      // Process the authentication request here
      // This involves displaying UI to the user
}
```

### Authentication Objects/Payloads <a href="#authentication-objectspayloads" id="authentication-objectspayloads"></a>

**Responding to Authentication Requests**[**​**](https://docs.reown.com/walletkit/android/one-click-auth#responding-to-authentication-requests)

To interact with authentication requests, build authentication objects (Wallet.Model.Cacao). It involves the following steps:

* **Creating an Authentication Payload Params** - Generate an authentication payload params that matches your application's supported chains and methods.
* **Formatting Authentication Messages** - Format the authentication message using the payload and the user's account.
* **Signing the Authentication Message** - Sign the formatted message to create a verifiable authentication object.

Example:

```json
ooverride val onSessionAuthenticate: ((Wallet.Model.SessionAuthenticate, Wallet.Model.VerifyContext) -> Unit)
  get() = { sessionAuthenticate, verifyContext ->
  val auths = mutableListOf<Wallet.Model.Cacao>()

  val authPayloadParams =
    WalletKit.generateAuthPayloadParams(
      sessionAuthenticate.payloadParams,
      supportedChains = listOf("eip155:1", "eip155:137", "eip155:56"), // Note: Only EVM chains are supported
      supportedMethods = listOf("personal_sign", "eth_signTypedData", "eth_sign")
  )

  authPayloadParams.chains.forEach { chain ->
    val issuer = "did:pkh:$chain:$address"
    val formattedMessage = StarTowerWalletKit.formatAuthMessage(Wallet.Params.FormatAuthMessage(authPayloadParams, issuer))

    val signature = signMessage(message: formattedMessage, privateKey: privateKey) //Note: Assume `signMessage` is a function you've implemented to sign messages.
    val auth = StarTowerWalletKit.generateAuthObject(authPayloadParams, issuer, signature)
    auths.add(auth)
  }
}
```

### Approving Authentication Requests <a href="#approving-authentication-requests" id="approving-authentication-requests"></a>

{% hint style="info" %}

1. The recommended approach for secure authentication across multiple chains involves signing a SIWE (Sign-In with Ethereum) message for each chain and account. However, at a minimum, one SIWE message must be signed to establish a session. It is possible to create a session for multiple chains with just one issued authentication object.
2. Sometimes a dapp may want to only authenticate the user without creating a session, not every approval will result with a new session.
   {% endhint %}

To approve an authentication request, construct Wallet.Model.Cacao instances for each supported chain, sign the authentication messages, generate AuthObjects and call approveSessionAuthenticate with the request ID and the authentication objects.

```json
 val approveAuthenticate = Wallet.Params.ApproveSessionAuthenticate(id = sessionAuthenticate.id, auths = auths)
StarTowerWalletKit.approveSessionAuthenticate(approveProposal,
  onSuccess = {
    //Redirect back to the dapp if redirect is set: sessionAuthenticate.participant.metadata?.redirect
  },
  onError = { error ->
      //Handle error
  }
)
```

### Rejecting Authentication Requests <a href="#rejecting-authentication-requests" id="rejecting-authentication-requests"></a>

If the authentication request cannot be approved or if the user chooses to reject it, use the rejectSessionAuthenticate method.

```cilkcpp
val rejectParams = Wallet.Params.rejectSessionAuthenticate(
    id = sessionAuthenticate.id,
    reason = "Reason"
)

StarTowerWalletKit.rejectSessionAuthenticate(rejectParams,
  onSuccess = {
        //Success
  },
  onError = { error ->
      //Handle error
  }
)
```

### Testing One-click Auth <a href="#testing-one-click-auth" id="testing-one-click-auth"></a>

You can use [AppKit Lab](https://appkit-lab.reown.com/library/ethers-siwe/) to test and verify that your wallet supports One-click Auth properly.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.startower.fr/get-started/developing-for-star-tower-wallet-platform/mobile-walletconnect/android/one-click-auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.