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

# Authorize Passkey Session

> Authenticate with an existing passkey and refresh session key for transaction signing.

<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 an authentication session for an existing passkey. Returns a URL to the hosted UI where the WebAuthn authentication ceremony takes place.

<Warning>
  The `session_key` parameter is **required** for authentication. The endpoint
  will return an error if session\_key is missing or null.
</Warning>

## Key Features

* **Session Refresh**: Creates new session key for existing passkey
* **Hosted UI**: Returns pre-configured URL with embedded challenge
* **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 authentication
* **redirectUrl** (string, optional): URL to redirect after completion

### session\_key (required)

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 is **mandatory** for authentication. The endpoint validates
  that session\_key is not null and will throw a `MissingSessionKey` error if
  omitted.
</Note>

<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 authentication ceremony:

```json theme={null}
{
  "url": "https://passkey.grid.squads.xyz/auth?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 new client-side session key using Solana's Keypair.generate()
  </Step>

  <Step title="Call Endpoint">
    POST to /passkeys/auth with meta\_info and session\_key (required)
  </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 and session key
  </Step>

  <Step title="Use for Transactions">
    Use the refreshed session key to sign Grid transactions
  </Step>
</Steps>

## Important Notes

* **Session Key Required**: Unlike passkey creation, authentication **must** include a session\_key
* **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
* **Session Validation**: Grid validates session expiration against Solana blockchain clock

## Error Handling

Common errors:

* **MissingSessionKey**: No session\_key provided (required for auth)
* **InvalidMetaInfo**: Missing or invalid appName
* **InvalidSessionKey**: Malformed session key format
* **InvalidBaseUrl**: Custom baseUrl format invalid
* **NoValidExternallySignedAccount**: Passkey not found

## Related Endpoints

* [Create Passkey Session](/grid/v1/api-reference/endpoint/passkeys/post) - Create new passkey
* [Submit Passkey Session](/grid/v1/api-reference/endpoint/passkeys/submit) - Submit WebAuthn response
* [Get Passkey Account](/grid/v1/api-reference/endpoint/passkeys/get-account) - Retrieve passkey details


## OpenAPI

````yaml POST /api/grid/v1/passkeys/auth
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/auth:
    post:
      tags:
        - passkeys
      summary: Authorize passkey session
      description: >-
        Authorize and refresh a passkey session. Requires a session key and
        returns a URL for session authorization flow with a challenge for
        session refresh.
      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/AuthorizePasskeySessionRequestPayload'
        required: true
      responses:
        '200':
          description: Passkey authorization URL created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizePasskeySessionResponsePayload'
        '400':
          description: Invalid request parameters or missing session key
        '500':
          description: Internal server error
      security:
        - bearer_auth: []
components:
  schemas:
    AuthorizePasskeySessionRequestPayload:
      type: object
      required:
        - metaInfo
      properties:
        baseUrl:
          type:
            - string
            - 'null'
        metaInfo:
          $ref: '#/components/schemas/MetaInfo'
        sessionKey:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SessionKey'
    AuthorizePasskeySessionResponsePayload:
      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

````