Introduction

​

Hosted UI Integration

• 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

​

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

​

Required Headers

• 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

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

• expiration: Seconds from now (e.g., 900 for 15 minutes)
• key: Solana public key string

• 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