Guides

SIWN: Connect Farcaster accounts

Connect for free using Sign In with Neynar (SIWN). The app gets read and/or write access, Neynar pays for onchain registration.

Suggest Edits

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

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 here for react and here 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

Updated 2 months ago