Skip to main content
Find passkey account
curl --request POST \
  --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 '
{
  "authenticatorResponse": {},
  "sessionKey": {
    "expiration": 1,
    "key": "11111111111111111111111111111111"
  }
}
'
{
  "passkey_account": "<string>",
  "session_key": {
    "expiration": 1,
    "key": "11111111111111111111111111111111"
  }
}
The “Try It” feature is disabled for this endpoint because it requires cryptographic WebAuthn authenticator response data that can only be generated during a browser WebAuthn ceremony. Use the Integration Guide for implementation examples.
Finds and retrieves a passkey account by submitting a WebAuthn authenticator response. This endpoint is useful for looking up passkey accounts when you have the authenticator credential but not the on-chain address.

​
Key Features

  • Authenticator Lookup: Find passkey using WebAuthn credential
  • Session Refresh: Returns new session key for found passkey
  • Cross-Device: Works across devices with synced passkeys
  • Account Recovery: Useful for account recovery flows

​
Request Body

​
authenticator_response (required)

The WebAuthn authenticator response from a get() ceremony: 
{
  "id": "credential-id",
  "rawId": "base64-encoded-raw-id",
  "response": {
    "clientDataJSON": "base64-encoded-client-data",
    "authenticatorData": "base64-encoded-authenticator-data",
    "signature": "base64-encoded-signature",
    "userHandle": "base64-encoded-user-handle"
  },
  "type": "public-key"
}

​
Response

Returns the passkey account address and session key: 
{
  "passkey_account": "7xK...abc",
  "session_key": {
    "key": "3pQ...ghi",
    "expiration": 1234567890
  }
}

​
Use Cases

​
Account Recovery

User forgot which account they used but has the passkey: 
// User initiates WebAuthn get() ceremony
const credential = await navigator.credentials.get({
  publicKey: {
    challenge: challenge,
    // ... other options
  },
});

// Find the associated passkey account
const response = await fetch(
  "https://grid.squads.xyz/api/grid/v1/passkeys/find",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_API_KEY",
      "x-grid-environment": "sandbox",
    },
    body: JSON.stringify({
      authenticator_response: credential,
    }),
  }
);

const data = await response.json();
console.log("Found passkey account:", data.passkey_account);

​
Cross-Device Login

User switches devices and needs to find their account: 
// On new device, prompt for passkey
const credential = await navigator.credentials.get({...});

// Find account using synced passkey
const account = await findPasskeyAccount(credential);

// Continue with account address
console.log("Account found:", account.passkey_account);

​
Multi-Passkey Management

Application supports multiple passkeys per user: 
// User selects which passkey to use
const credential = await selectPasskey();

// Find which account it's associated with
const account = await findPasskeyAccount(credential);

// Use correct account for operations
useAccount(account.passkey_account);

​
Implementation Flow

1

Initiate Get Ceremony

User triggers WebAuthn get() with appropriate challenge
2

Retrieve Credential

Browser/device returns authenticator response
3

Submit to Find

POST authenticator response to /passkeys/find
4

Receive Account

Get passkey account address and fresh session key
5

Use Account

Continue with account operations using returned address

​
Important Notes

  • Complete Response Required: Submit entire WebAuthn authenticator response
  • Valid Signature: Response must contain valid ES256 signature
  • Fresh Session: Returns new session key regardless of existing session status
  • User Presence: Authenticator response must verify user presence
  • Account Lookup: Searches for account matching the credential ID

​
Error Handling

Common errors:
  • NoValidExternallySignedAccount: No passkey account found for this credential
  • InvalidAuthenticatorResponse: Malformed WebAuthn response
  • InvalidSignature: Signature verification failed
  • MissingCredential: Credential ID not provided in response

​
Response Fields

​
passkey_account

The on-chain Solana address of the passkey account associated with this authenticator credential.

​
session_key

Fresh session key for transaction signing:
  • key: Public key in base58 format
  • expiration: Unix timestamp when session expires

​
Security Considerations

  • Signature Verification: Endpoint verifies WebAuthn signature before lookup
  • User Presence: Authenticator must prove user presence
  • Fresh Session: Each find operation generates new session key
  • No Account Creation: This endpoint only finds existing accounts, doesn’t create new ones

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
​
authenticatorResponse
object
required
​
sessionKey
object
required

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 account found successfully

​
passkey_account
string
required
​
session_key
object
required

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.