Skip to main content
Submit passkey session
curl --request POST \
  --url https://grid.squads.xyz/api/grid/v1/passkeys/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-grid-environment: <x-grid-environment>' \
  --data '
{
  "authenticatorResponse": {
    "response": {
      "authenticatorData": "<string>",
      "clientDataJSON": "<string>",
      "publicKey": "<string>",
      "signature": "<string>"
    }
  },
  "ceremonyType": "create",
  "sessionKey": {
    "expiration": 1,
    "key": "11111111111111111111111111111111"
  },
  "slotNumber": 1
}
'
{
  "passkeyAccount": "<string>",
  "sessionKey": {
    "expiration": 1,
    "key": "11111111111111111111111111111111"
  },
  "smartAccount": "<unknown>"
}
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.
Submits the WebAuthn authenticator response to complete the passkey creation or authentication ceremony. Processes the ceremony data and performs on-chain transaction to initialize or refresh the passkey.

​
Key Features

  • WebAuthn Processing: Validates and processes authenticator responses
  • On-Chain Transaction: Executes blockchain transaction for passkey initialization/refresh
  • Session Management: Returns session key for transaction signing
  • Smart Account Integration: Optionally returns smart account data

​
Request Body

​
ceremonyType (required)

Type of WebAuthn ceremony:
  • “Create”: For new passkey creation
  • “Auth”: For existing passkey authentication

​
sessionKey (required)

  • sessionKey (string): The session key public key associated with this ceremony

​
slotNumber (required)

  • slotNumber (number): Solana slot number from the challenge URL for replay protection

​
authenticatorResponse (required)

The complete WebAuthn authenticator response object from the browser’s WebAuthn API: 
{
  "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 details and session key: 
{
  "passkey_account": "7xK...abc", // On-chain passkey address
  "session_key": {
    "key": "9yM...def", // Session key public key
    "expiration": 1234567890 // Unix timestamp
  },
  "smart_account": {
    // Optional: Only for create ceremony with smart account creation
    "address": "5nP...xyz",
    "type": "multisig",
    "status": "active"
  }
}

​
Implementation Flow

1

Complete WebAuthn Ceremony

User completes passkey creation or authentication in hosted UI or custom UI
2

Extract Response

Retrieve the complete authenticator response from the WebAuthn API
3

Submit to API

POST to /passkeys/submit with ceremony type, session key, slot, and response
4

Process Result

Receive passkey_account address and session_key for transaction signing
5

Store Credentials

Securely store passkey address and session key for future transactions

​
Important Notes

  • Complete Response Required: Submit the entire WebAuthn authenticator response object
  • Ceremony Type: Must match the original session type (Create or Auth)
  • Slot Validation: Slot number must match the challenge for replay protection
  • On-Chain Transaction: This endpoint executes a transaction on Solana
  • ES256 Only: Only ES256 (algorithm -7) signatures are supported
  • User Presence: Authenticator response must verify user presence

​
Error Handling

Common errors:
  • InvalidAuthenticatorResponse: Malformed WebAuthn response
  • InvalidCeremonyType: Unknown ceremony type
  • InvalidSlotNumber: Slot mismatch or replay detected
  • InvalidSessionKey: Session key doesn’t match ceremony
  • NoValidExternallySignedAccount: Account not found (for Auth ceremony)
  • TransactionFailed: On-chain transaction failed

​
Response Fields

​
passkey_account

The on-chain Solana address of the passkey account that can be used as a signer in Grid operations.

​
session_key

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

​
smart_account (optional)

Only returned if a smart account was created during this ceremony:
  • address: Grid smart account Solana address
  • type: Account type (typically “multisig”)
  • status: Account status (“active”, “pending”, etc.)

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
​
ceremonyType
enum<string>
required
Available options:
create,
auth
​
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.

​
slotNumber
integer<int64>
required
Required range: x >= 0

Response

Passkey session submitted successfully. If the passkey is a signer on a smart account, smart_account data will be included in the response.

​
passkeyAccount
string
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.

​
smartAccount
object