Skip to main content
Get passkey session
curl --request GET \
  --url https://grid.squads.xyz/api/grid/v1/passkeys/find \
  --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.
Generates a session URL containing a WebAuthn challenge for passkey account lookup operations. This endpoint is used when you need to find a passkey account but don’t have the authenticator response yet.
This endpoint returns a URL for initiating a passkey lookup ceremony, while Find Passkey Account (POST /passkeys/find) accepts an authenticator response and returns account details.

​
Key Features

  • Challenge Generation: Creates secure WebAuthn challenge
  • Session URL: Returns URL for passkey lookup flow
  • Hosted UI Compatible: Can be used with hosted UI
  • Custom Domain Support: Works with custom baseUrl configuration

​
Response

Returns a URL for the passkey lookup ceremony: 
{
  "url": "https://passkey.grid.squads.xyz/find?challenge=..."
}
The URL includes:
  • challenge: Base64 encoded challenge for WebAuthn (valid for 60 seconds)
  • slot: Solana slot number for replay protection
  • Configuration: Parameters for the lookup ceremony

​
Use Cases

​
Hosted UI Lookup

Use the returned URL in an iframe or WebBrowser for guided passkey lookup: 
// Get session URL
const response = await fetch(
  "https://grid.squads.xyz/api/grid/v1/passkeys/find",
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "x-grid-environment": "sandbox",
    },
  }
);

const data = await response.json();

// Load in iframe
document.querySelector("iframe").src = data.url;

// Listen for completion
window.addEventListener("message", (event) => {
  if (event.data.type === "passkey_found") {
    console.log("Passkey account:", event.data.passkeyAddress);
  }
});

​
Account Recovery Flow

Integrate into account recovery user experience: 
// User clicks "Find my account"
const sessionUrl = await getPasskeySession();

// Show recovery UI
showRecoveryModal(sessionUrl);

// Handle result
onRecoveryComplete((passkeyAddress) => {
  // Redirect to account
  navigateTo(`/account/${passkeyAddress}`);
});

​
Multi-Account Selection

Let users choose which passkey/account to use: 
// Start passkey selection flow
const sessionUrl = await getPasskeySession();

// User selects passkey
const selected = await showPasskeyPicker(sessionUrl);

// Use selected account
activateAccount(selected.passkeyAddress);

​
Implementation Flow

1

Request Session URL

GET /passkeys/find to retrieve session URL
2

Load UI

Display URL in iframe (web) or WebBrowser (mobile)
3

User Selects Passkey

User completes WebAuthn get() ceremony
4

Receive Result

Hosted UI returns passkey account address via postMessage or redirect
5

Use Account

Continue with operations using found account address

​
Important Notes

  • Challenge Expiration: URL is valid for 60 seconds from generation
  • No Session Key: This endpoint doesn’t create a session key (use /passkeys/auth for that)
  • Lookup Only: Finds existing passkey accounts, doesn’t create new ones
  • User Interaction: Requires user to complete WebAuthn ceremony
  • GET vs POST: GET returns URL, POST /passkeys/find accepts response

​
Comparison with POST /passkeys/find

FeatureGET /passkeys/find (This Endpoint)POST /passkeys/find
PurposeGet session URL for lookupSubmit response to find account
InputNone (headers only)Authenticator response
OutputURL with challengePasskey account address + session
Use CaseStart lookup flowComplete lookup with response
Hosted UI CompatibleYesNo (direct API call)
Creates Session KeyNoYes

​
URL Structure

The returned URL contains: 
https://passkey.grid.squads.xyz/find?
  challenge=<base64-challenge>&
  slot=<solana-slot>&
  app_name=<optional>&
  redirect_url=<optional>

​
Error Handling

Common errors:
  • ChallengeGenerationFailed: Unable to create challenge
  • SlotRetrievalFailed: Couldn’t get Solana slot
  • RateLimitExceeded: Too many requests

​
Security Considerations

  • Challenge Uniqueness: Each request generates a unique challenge
  • Time-Limited: Challenge valid for 60 seconds only
  • Replay Protection: Slot number prevents replay attacks
  • HTTPS Required: All URLs use HTTPS
  • No Sensitive Data: URL contains only public challenge data

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 retrieved successfully

​
url
string
required