​
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
Before starting, there are two reasons you might want to use one of our other signer products:
  • if building a mini app
  • if you want your own app’s branding on the Farcaster approval screen (example screenshot for this below)
If either of the above use cases is true, see one of the following pages instead:Example of Neynar brand vs another brand showing up on the approval screen:
Neynar branded approval screenDeveloper branded approval screen

​
How to integrate SIWN?

​
Example integration

Check out this sample application (github) 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

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

Go to the Neynar Developer Portal 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). Atleast one permission is needed. Defaults to — Read and write — permission.

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

<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 for react native.
Want to customize the button to your liking? See 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, 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 forstatusCode: 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 and the signer_uuid to do any write actions on behalf of the user in your App. You can try this flow yourself at 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
    • 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 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 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 eventData in through params example