Skip to main content
Create passkey session
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/passkeys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-grid-environment: <x-grid-environment>' \
  --data '
{
  "metaInfo": {
    "appName": "<string>",
    "redirectUrl": "<string>"
  },
  "baseUrl": "<string>",
  "sessionKey": "<unknown>"
}
'
{
  "url": "<string>"
}
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 for implementation examples.
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)
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).

​
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: 
{
  "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

1

Generate Session Key

Create a client-side session key using Solana’s Keypair.generate()
2

Call Endpoint

POST to /passkeys with meta_info and sessionKey
3

Load URL

Display the returned URL in an iframe (web) or WebBrowser (mobile)
4

Handle Completion

Listen for postMessage events with the passkey address
5

Create Smart Account

Use the passkey address to create a Grid smart account

​
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 endpoint to deploy a Grid account

​
Error Handling

Common errors:
  • InvalidMetaInfo: Missing or invalid appName
  • InvalidSessionKey: Malformed session key
  • InvalidBaseUrl: Custom baseUrl format invalid

Authorizations

​
Authorization
string
header
required

Your Grid API key from the Grid Dashboard

Headers

​
x-grid-environment
string
required

Solana network environment (sandbox, devnet, mainnet)

Body

application/json
​
metaInfo
object
required
​
baseUrl
string | null
​
sessionKey
object

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.

Response

Passkey session URL created successfully

​
url
string
required