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
• Smart Account Creation: Automatically creates Grid smart accounts with passkeys

​

Key Features

• WebAuthn Integration: Industry-standard passkey creation and authentication
• Smart Account Creation: One-step account creation with pass key as initial signer
• Session Management: Secure session tokens for seamless transaction signing
• Database Integration: Full Grid account lifecycle management
• 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
• Devnet Funding: Automatic USDC funding for devnet accounts

​

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-grid-environment: sandbox or production
• Content-Type: application/json

​

How It Works

​

Smart Account Creation Flow

1. Generate Session Key: Create a client-side session key using Keypair.generate()
2. Request Passkey Session: Call the passkeys endpoint to get a hosted UI URL
3. Complete WebAuthn Ceremony: User creates passkey via hosted UI
4. Create Smart Account: Grid automatically creates a 1/1 threshold smart account with the passkey as signer
5. Receive Account Details: Get back smart account address, passkey address, and session key
6. Use for Transactions: The passkey can immediately sign transactions for the smart account

​

Authentication Flow

1. Generate Session Key: Create a new session key for authentication
2. Request Auth Session: Call the passkeys/auth endpoint
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 passkey address
6. Use as Signer: Include the passkey address as a transaction signer in Grid account operations
7. Sign Requests: Use the session key to sign subsequent transactions

​

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

​

Smart Account Properties

• Threshold: 1/1 (single signer required)
• Passkey Permissions: Full permissions (mask=7: CAN_INITIATE | CAN_VOTE | CAN_EXECUTE)
• Database Integration: Stored in Grid database with full lifecycle management
• Devnet Funding: Automatically funded with 1 USDC on sandbox environment

​

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
• Environment-Specific: Smart accounts have different addresses in sandbox vs production

​

Error Handling

​

Common Errors

​

Error Response Format

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

​

Security Considerations

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

​

API Endpoints

• Create Passkey Session - Initialize passkey creation
• Authorize Passkey Session - Authenticate with existing passkey
• Submit Passkey Session - Complete WebAuthn ceremony
• Create Smart Account - Create account with passkey
• Get Passkey Account - Retrieve passkey details
• Find Passkey Account - Lookup passkey by authenticator
• Get Passkey Session - Retrieve session URL

​

Getting Started