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

# Create Passkey Session

> Initialize a passkey creation session and receive a hosted UI URL for WebAuthn ceremony.

<Warning>
  The "Try It" feature is disabled for this endpoint because it initiates a WebAuthn ceremony that returns a URL. Testing requires completing the ceremony in a browser. Use the [Integration Guide](/grid/v1/accounts/passkeys/integration-guide) for implementation examples.
</Warning>

Creates a new passkey session for registering a passkey on a user's device. Returns a URL to the hosted UI where the WebAuthn passkey creation ceremony takes place.

## Key Features

* **Hosted UI**: Returns a pre-configured URL with embedded challenge
* **Session Management**: Associates session key for transaction signing
* **Custom Domains**: Support for custom baseUrl configuration
* **Cross-Platform**: Works on web, mobile, and across devices

## Request Body

### meta\_info (required)

Configuration for the hosted UI:

* **appName** (string): Display name shown to users during passkey creation
* **redirectUrl** (string, optional): URL to redirect after completion

### sessionKey (optional)

Session key configuration:

* **key** (string): Solana public key in base58 format
* **expiration** (number): Seconds from now until expiration (e.g., 900 for 15 minutes)

<Note>
  The session key format in the request uses **seconds from now** for
  expiration, but the response returns a **Unix timestamp**. For example, if
  you send `expiration: 900`, you'll receive back `expiration: 1234567890`
  (current time + 900 seconds).
</Note>

### baseUrl (optional)

* **baseUrl** (string): Custom domain for hosting the passkey flow (e.g., `https://auth.yourcompany.com`)
* If omitted, uses the default Grid hosted UI

## Response

Returns a URL for the passkey creation ceremony:

```json theme={null}
{
  "url": "https://passkey.grid.squads.xyz/create?challenge=..."
}
```

The URL includes:

* **challenge**: Base64 encoded challenge for WebAuthn (valid for 60 seconds)
* **slot**: Solana slot number for replay protection
* **Other params**: Configuration for the hosted UI

## Implementation Flow

<Steps>
  <Step title="Generate Session Key">
    Create a client-side session key using Solana's Keypair.generate()
  </Step>

  <Step title="Call Endpoint">
    POST to /passkeys with meta\_info and sessionKey
  </Step>

  <Step title="Load URL">
    Display the returned URL in an iframe (web) or WebBrowser (mobile)
  </Step>

  <Step title="Handle Completion">
    Listen for postMessage events with the passkey address
  </Step>

  <Step title="Create Smart Account">
    Use the passkey address to create a Grid smart account
  </Step>
</Steps>

## Important Notes

* **Challenge Expiration**: URL is valid for 60 seconds from generation
* **Session Format**: Request uses relative seconds, response uses Unix timestamp
* **Algorithm**: Only ES256 (algorithm `-7`) is supported
* **User Presence**: WebAuthn must verify user presence
* **Next Step**: After successful passkey creation, use the [Create Smart Account](/grid/v1/api-reference/endpoint/passkeys/create-account) endpoint to deploy a Grid account

## Error Handling

Common errors:

* **InvalidMetaInfo**: Missing or invalid appName
* **InvalidSessionKey**: Malformed session key
* **InvalidBaseUrl**: Custom baseUrl format invalid

## Related Endpoints

* [Authorize Passkey Session](/grid/v1/api-reference/endpoint/passkeys/auth) - Authenticate with existing passkey
* [Submit Passkey Session](/grid/v1/api-reference/endpoint/passkeys/submit) - Submit WebAuthn response
* [Create Smart Account](/grid/v1/api-reference/endpoint/passkeys/create-account) - Deploy account with passkey


## OpenAPI

````yaml POST /api/grid/v1/passkeys
openapi: 3.1.0
info:
  title: Grid v1 API
  description: Grid v1 REST API for Solana-based smart account system
  contact:
    name: Grid API Support
    url: https://squads.so
    email: support@squads.so
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://grid.squads.xyz
    description: Production server
security:
  - bearer_auth: []
tags:
  - name: accounts
    description: Smart account management operations
  - name: spending-limits
    description: Spending limit management
  - name: standing-orders
    description: Standing order operations
  - name: transactions
    description: Transaction management
  - name: trade
    description: Trade operations and management
  - name: payments
    description: Payment intent operations
  - name: passkeys
    description: Passkey management
  - name: kyc
    description: Know Your Customer operations
  - name: external-accounts
    description: External bank account management
  - name: virtual-accounts
    description: Virtual account management
  - name: auth
    description: Authentication operations
  - name: proposals
    description: Proposal management for multi-sig operations
  - name: compliance
    description: Compliance entity management and KYB/KYC operations
paths:
  /api/grid/v1/passkeys:
    post:
      tags:
        - passkeys
      summary: Create passkey session
      description: >-
        Initiate a new passkey creation session. Returns a URL for the passkey
        creation flow with challenge and session parameters.
      operationId: handler
      parameters:
        - name: x-grid-environment
          in: header
          description: Solana network environment (sandbox, devnet, mainnet)
          required: true
          schema:
            type: string
          example: sandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePasskeySessionRequestPayload'
        required: true
      responses:
        '200':
          description: Passkey session URL created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePasskeySessionResponsePayload'
        '400':
          description: Invalid request parameters
        '500':
          description: Internal server error
      security:
        - bearer_auth: []
components:
  schemas:
    CreatePasskeySessionRequestPayload:
      type: object
      required:
        - metaInfo
      properties:
        baseUrl:
          type:
            - string
            - 'null'
        metaInfo:
          $ref: '#/components/schemas/MetaInfo'
        sessionKey:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SessionKey'
    CreatePasskeySessionResponsePayload:
      type: object
      required:
        - url
      properties:
        url:
          type: string
    MetaInfo:
      type: object
      required:
        - appName
      properties:
        appName:
          type: string
        redirectUrl:
          type:
            - string
            - 'null'
    SessionKey:
      type: object
      description: >-
        Grid v1 API SessionKey type that supports backward-compatible
        deserialization

        from both raw bytes array (old format) and base58 string (new format).

        Always serializes to base58 string format.
      required:
        - key
        - expiration
      properties:
        expiration:
          type: integer
          format: int64
          minimum: 0
        key:
          type: string
          example: '11111111111111111111111111111111'
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: Your Grid API key from the Grid Dashboard

````