## What is SIWN?

SIWN enables seamless authentication + authorization for Farcaster clients that need read and write permissions on behalf of their users.

- Users don’t need to pay for warps to try apps
- Developers don’t need to worry about onboarding funnel drop-offs when OP mainnet gas surges

- **If building a mini app**, use [App auth](https://docs.neynar.com/docs/mini-app-authentication) instead
- If you want to design your own frontend, use [Neynar Managed Signers](https://docs.neynar.com/docs/integrate-managed-signers)

## How to integrate SIWN?

### Example integration

Check out this sample application ([github](https://github.com/neynarxyz/farcaster-examples/tree/main/wownar)) that integrates Sign in with Neynar and allows users to cast. A live demo of this exact code has been deployed at [https://demo.neynar.com](https://demo.neynar.com/)

### Step 0: Set up your app in the Neynar developer portal

Go to the [Neynar Developer Portal](https://dev.neynar.com/) settings tab and update the following

1. **Name -** Displayed to the user in Step 3.
2. **Logo URL** - Displayed to the user in Step 3. Use a PNG or SVG format.
3. **Authorized origins** - Authorized origins are the HTTP origins that host your web application. e.g. `https://demo.neynar.com` This is required to pass user credentials back to your application securely. This cannot contain wildcards or IP addresses.
4. **Permissions** - Generated signers will have these permissions (Read only and Read and write). At least one permission is needed. **Defaults to — Read and write — permission.**

### Step 1: Display the SIWN button on your app frontend

HTML

```html
<html>
  <body>
    <div
      class="neynar_signin"
      data-client_id="YOUR_NEYNAR_CLIENT_ID"
      data-success-callback="onSignInSuccess"
      data-theme="dark"> <!-- defaults to light, unless specified -->
    </div>
		<script src="https://neynarxyz.github.io/siwn/raw/1.2.0/index.js" async></script>
		<script>
      // Define the onSignInSuccess callback function
      function onSignInSuccess(data) {
        console.log("Sign-in success with data:", data);
        // Your code to handle the sign-in data
      }
	   </script>
  </body>
</html>
```

### Example above is for web. See [React Implementation](/docs/react-implementation) for react and [React Native Implementation](https://docs.neynar.com/docs/sign-in-with-neynar-react-native-implementation) for react native.

Want to customize the button to your liking? See [How to customize Sign In with Neynar button in your app](https://docs.neynar.com/docs/how-to-customize-sign-in-with-neynar-button-in-your-app)

### Step 2: Fill in `data-client_id` in the button code

Find this value in [Neynar Developer Portal](https://dev.neynar.com/), Settings tab. e.g. `00b75745-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

### Step 3: Handle callback

Once the user is authenticated and a signer has been authorized by the user, the `signer_uuid` and `fid` will be passed in via the `data` object in the callback function.

- `signer_uuid` is unique to your app and is used to write to Farcaster on behalf of the user (same uuid format)
- `fid`: This is the unique Farcaster identifier for the user e.g. `6131`
- `user`: Neynar hydrated user object.

Store the `signer_uuid` securely on your backend or the browser’s local storage; it’s not meant to be exposed to the user or anyone other than you. Switch the app to the logged-in state for that Farcaster user. Handle insufficient permissions for the API calls except for `statusCode: 403`, `errorResponse.code: InsufficientPermission`

### That’s it!

**You’re all set!** The user is now logged in, and you should use the `fid` for any [read APIs](https://docs.neynar.com/docs/what-does-vitalikeths-farcaster-feed-look-like) and the `signer_uuid` to do any [write actions](https://docs.neynar.com/docs/liking-and-recasting-with-neynar-sdk) on behalf of the user in your App. You can try this flow yourself at **[demo.neynar.com](https://demo.neynar.com/)**

## Appendix — more about the user journey

### 1. The user clicks the SIWN button, App redirects to Neynar auth flow

- After the user clicks the SIWN button, the script opens a new popup window for user authentication with Neynar and listens for a message from this window

### 2. The user goes through Neynar’s sign-in flow

- The user runs through the following steps on [https://app.neynar.com/login](https://app.neynar.com/login)  - authentication (only needed if the user isn’t authenticated on app.neynar.com)
  - signer collection (only needed if Neynar doesn’t have a signer for the user) — For now, the signer is collected from the user for **Read only** permissions as well; future iterations will remove this step for **Read only** permissions —
  - authorization (this is where the user approves the permissions, and these permissions are assigned to the user’s signer)
- No integration actions are needed from the app developer for this step

### 3. The user is routed back to the App, App collects user information

- Once the user is authenticated, the script receives a message from the authentication window.
- It then executes a callback function
- In the onSignInSuccess function, the user will event data in through params.