Introduction

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

​

Platform Support

• Web: React/Next.js with iframe integration
• Mobile: React Native with WebBrowser API
• Cross-Platform: Works across devices and platforms

​

Supported Password Managers

​

API Access

​

Base URL

Production: https://developer-api.squads.so/api/v1/

​

Required Headers

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:

1. Local Passkey Creation: WebAuthn creates a passkey locally on your device/browser
2. On-Chain Account Creation: The API creates an associated Solana account on the blockchain

​

Authentication Flow

1. Generate Session Key: Create a client-side session key using Keypair.generate()
2. Request Passkey Session: Call the passkeys endpoint with action type (create, auth, or get) and the generated session key
3. Get Hosted UI URL: Receive a secure URL for the WebAuthn ceremony (valid for 60 seconds)
4. 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.
5. Handle Completion: Listen for postMessage events or extract search params from the redirect URL containing the onchain passkey address
6. Use as Signer: Include the onchain passkey address as a transaction signer in Smart Account operations
7. 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 Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": "Additional context"
  }
}

​

Security Considerations

1. Network Restrictions: Currently limited to devnet for security
2. Session Key Expiration: Automatic validation of session timestamps
3. RP ID Validation: Relying Party IDs are limited to 32 bytes
4. Slot Validation: Solana slot numbers provide replay protection
5. Challenge Expiration: WebAuthn challenges expire after 60 seconds
6. Secure Storage: Store session keys securely on client side
7. HTTPS Required: All communications must use HTTPS
8. Origin Validation: Ensure proper origin/redirect URL configuration

​

API Endpoint

• Create or Authenticate - Create passkey session URLs for the hosted UI

​

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.