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.
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
- Name - Displayed to the user in Step 3.
- Logo URL - Displayed to the user in Step 3. Use a PNG or SVG format.
- 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. - 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
data-client_id
in the button codeFind 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 about 2 months ago