Skip to main content
Authorize passkey session
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/passkeys/auth \
  --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 an authentication session for an existing passkey. Returns a URL to the hosted UI where the WebAuthn authentication ceremony takes place.
The session_key parameter is required for authentication. The endpoint will return an error if session_key is missing or null.

​
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)
The session key is mandatory for authentication. The endpoint validates that session_key is not null and will throw a MissingSessionKey error if omitted.
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 authentication ceremony: 
{
  "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

1

Generate Session Key

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

Call Endpoint

POST to /passkeys/auth with meta_info and session_key (required)
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 and session key
5

Use for Transactions

Use the refreshed session key to sign Grid transactions

​
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

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 authorization URL created successfully

​
url
string
required