> ## Documentation Index
> Fetch the complete documentation index at: https://developers.squads.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Create and authenticate with passkeys for secure, passwordless Smart Account transactions.

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

| 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/`

### 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 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 Response Format

```json theme={null}
{
  "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

## API Endpoint

* **[Create or Authenticate](/squads-api/api-reference/v1/endpoint/passkeys/auth)** - Create passkey session URLs for the hosted UI

## Getting Started

**Hosted UI Integration**: See the [Passkey Integration Guide](/squads-api/passkeys/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](/squads-api/passkeys/advanced-integration).