Skip to main content

​
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 [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