The Smart Account API provides passkey-based authentication for Smart Account transactions using the WebAuthn protocol. This enables secure, passwordless authentication with biometric or hardware-based passkeys as transaction signers.
Hosted UI Integration
The Squads Passkey API provides a production-ready hosted interface that handles all WebAuthn complexity for you. This is the recommended approach for most applications.
Key Benefits:
- Quick Integration: Simple iframe or WebBrowser integration
- Production-Ready: Fully tested and optimized UI
- Cross-Platform: Works seamlessly on web and mobile
- Handles Complexity: WebAuthn protocol managed for you
- No WebAuthn Expertise Required: Just integrate the hosted interface
Best For: Most applications, rapid development, teams without WebAuthn expertise
Key Features
- WebAuthn Integration: Industry-standard passkey creation and authentication
- Session Management: Secure session tokens for seamless transaction signing
- Smart Account Integration: Passkeys work as transaction signers in all Smart Account operations
- Cross-Platform Support: Works on web, mobile, and across devices
- Hardware Security: Support for hardware keys like Yubikey
- Biometric Authentication: Fingerprint, Face ID, and other biometric methods
Passkeys are currently only live on devnet. Mainnet support is coming soon.
- Web: React/Next.js with iframe integration
- Mobile: React Native with WebBrowser API
- Cross-Platform: Works across devices and platforms
Supported Password Managers
Password Manager | Type | Notes | Supported |
---|
Chrome | Browser Native | Built-in password manager | ✅ |
Chrome Cross-Platform | Browser Sync | Works via QR code & Apple Passwords | ✅ |
Apple Passwords | OS Native | Native iOS integration | ✅ |
Yubikey | Hardware Key | Physical security key | ✅ |
1Password | Third Party | Cross-platform support | ✅ |
Dashlane | Third Party | Cross-platform support | ✅ |
NordPass | Third Party | Not currently supported | ❌ |
API Access
Base URL
Production: https://developer-api.squads.so/api/v1/
All endpoints require:
- Authorization:
Bearer YOUR_API_KEY
(UUID-based API key)
- x-squads-network:
devnet
or mainnet
- Content-Type:
application/json
How It Works
Two-Step Registration Process
Passkey registration involves two separate steps that must both succeed:
- Local Passkey Creation: WebAuthn creates a passkey locally on your device/browser
- On-Chain Account Creation: The API creates an associated Solana account on the blockchain
Authentication Flow
- Generate Session Key: Create a client-side session key using
Keypair.generate()
- Request Passkey Session: Call the passkeys endpoint with action type (
create
, auth
, or get
) and the generated session key
- Get Hosted UI URL: Receive a secure URL for the WebAuthn ceremony (valid for 60 seconds)
- Load in iframe: Display the URL in a hidden iframe to initiate the WebAuthn ceremony. On mobile devices, open the URL in a new window or tab instead of an iframe to ensure proper WebAuthn support.
- Handle Completion: Listen for postMessage events or extract search params from the redirect URL containing the onchain passkey address
- Use as Signer: Include the onchain passkey address as a transaction signer in Smart Account operations
- Sign Requests: Use the session key to sign subsequent smart account transactions for authentication
Session Key Management
Input Format (when creating sessions):
- expiration: Seconds from now (e.g., 900 for 15 minutes)
- key: Solana public key string
Output Format (in API responses):
- expiration: Unix timestamp
- key: Solana public key string
Important Notes
- Challenge Expiration: WebAuthn challenges expire after 60 seconds
- User Presence Required: All operations require user presence verification
- Algorithm Support: Only ES256 (algorithm
-7
) is supported
- Session Key Properties: Temporary, scoped, refreshable, and secure
Error Handling
Common Errors
Error Code | Description | Solution |
---|
InvalidNetwork | Operation not supported on mainnet | Use devnet |
MissingSessionKey | Session key required for auth actions | Provide valid session key |
InvalidAuthenticatorResponse | Malformed WebAuthn response | Validate WebAuthn data |
NoValidExternallySignedAccount | Account not found | Verify account exists |
InvalidExternallySignedAccountAddress | Invalid account address format | Use valid Solana address |
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message",
"details": "Additional context"
}
}
Security Considerations
- Network Restrictions: Currently limited to devnet for security
- Session Key Expiration: Automatic validation of session timestamps
- RP ID Validation: Relying Party IDs are limited to 32 bytes
- Slot Validation: Solana slot numbers provide replay protection
- Challenge Expiration: WebAuthn challenges expire after 60 seconds
- Secure Storage: Store session keys securely on client side
- HTTPS Required: All communications must use HTTPS
- Origin Validation: Ensure proper origin/redirect URL configuration
API Endpoint
Getting Started
Hosted UI Integration: See the Passkey Integration Guide for complete implementation examples with iframe and WebBrowser integration.
Need Your Own Custom Domain? If you need to host passkey flows on your own domain (e.g., auth.yourcompany.com
) for branding or compliance requirements, see Custom Domain.
Responses are generated using AI and may contain mistakes.