> ## 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 Grid account transactions.

The Grid API provides passkey-based authentication for Grid accounts using the WebAuthn protocol. This enables secure, passwordless authentication with biometric or hardware-based passkeys, including seamless smart account creation.

## Hosted UI Integration

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

**Best For**: Most applications, rapid development, teams without WebAuthn expertise

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

| 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://grid.squads.xyz/api/grid/v1/`

### Required Headers

All endpoints require:

* **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

Grid passkeys automatically create complete smart accounts:

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

For existing passkeys:

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

**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

### Smart Account Properties

Accounts created with passkeys have these default 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 Code                              | Description                           | Solution                  |
| --------------------------------------- | ------------------------------------- | ------------------------- |
| `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
8. **Environment Isolation**: Never send production funds to sandbox addresses

## API Endpoints

* **[Create Passkey Session](/grid/v1/api-reference/endpoint/passkeys/post)** - Initialize passkey creation
* **[Authorize Passkey Session](/grid/v1/api-reference/endpoint/passkeys/auth)** - Authenticate with existing passkey
* **[Submit Passkey Session](/grid/v1/api-reference/endpoint/passkeys/submit)** - Complete WebAuthn ceremony
* **[Create Smart Account](/grid/v1/api-reference/endpoint/passkeys/create-account)** - Create account with passkey
* **[Get Passkey Account](/grid/v1/api-reference/endpoint/passkeys/get-account)** - Retrieve passkey details
* **[Find Passkey Account](/grid/v1/api-reference/endpoint/passkeys/find)** - Lookup passkey by authenticator
* **[Get Passkey Session](/grid/v1/api-reference/endpoint/passkeys/get-session)** - Retrieve session URL

## Getting Started

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