Custom Domain

The advanced integration approach allows you to host passkey flows on your own custom domain (e.g., auth.yourcompany.com) while leveraging the Squads API to proxy WebAuthn requests to the blockchain.

Primary Use Case: Custom Domain - Host passkey authentication on your own domain instead of the default Squads domain for branding, compliance, or security requirements.

​

When to Use Advanced Integration

Choose this approach when you need:

• Custom Domain: Host passkey flows on auth.yourcompany.com instead of passkey.grid.squads.xyz
• Compliance Requirements: Internal policies require authentication to happen on company domains
• Brand Consistency: Maintain your brand throughout the entire authentication flow
• Security Policies: Security requirements mandate own domain usage

​

How It Works

​

WebAuthn Proxy Flow

1. Create Session: Use the auth endpoint with your custom baseUrl
2. Extract Challenge: Parse the challenge from the returned URL
3. WebAuthn Ceremony: Implement WebAuthn protocol on your domain with proper ES256 support
4. Submit Response: Use the submit-passkey-session endpoint to process the response
5. Get Account: Retrieve the account using the externally-signed-account endpoint

​

Custom UI Requirements

When implementing a custom passkey UI, your implementation must:

1. Extract the challenge: Parse the challenge parameter from the URL
2. Use challenge directly: Pass the challenge to the WebAuthn protocol as-is (already base64 encoded)
3. Do NOT re-encode: The challenge is already base64 encoded - additional encoding will cause errors
4. Return complete response: For authentication, return the entire WebAuthn authentication response object
5. Time constraint: The challenge is only valid for 60 seconds from URL generation

​

Advanced API Endpoints

For custom UI implementations, use these advanced endpoints:

• Submit Passkey Session - Process WebAuthn responses
• Get Externally Signed Account - Retrieve account from response
• Get Account Data - Get detailed account information

​

MetaInfo and BaseURL Usage

​

Default vs Custom BaseURL

• Default baseUrl: When using the default https://passkey.grid.squads.xyz, the metaInfo fields are used by the hosted UI
• Custom baseUrl: Use your custom domain (e.g., https://auth.yourcompany.com) - your UI handles passkey identification and naming

​

Example Configuration

{
  "action": "create",
  "sessionKey": {
    "key": "your-session-key",
    "expiration": 900
  },
  "metaInfo": {
    "appName": "YourCompany App",
    "redirectUrl": "https://yourapp.com/auth-callback"
  },
  "baseUrl": "https://auth.yourcompany.com"
}

​

WebAuthn Configuration Requirements

​

Required Settings

The on-chain passkey program has specific requirements:

User Presence Required:

• userPresent must be true in the WebAuthn authenticator response
• The authenticator must verify user presence through biometric, PIN, or physical interaction

Algorithm Requirement:

• Only ES256 (algorithm -7) is supported
• No other cryptographic algorithms are accepted

WebAuthn Configuration Example:

// For passkey creation
const createOptions = {
  publicKey: {
    challenge: challenge, // From API URL - already base64 encoded
    rp: { name: "Your Company" },
    user: {
      /* user info */
    },
    pubKeyCredParams: [{ alg: -7, type: "public-key" }], // REQUIRED: Only -7 (ES256) supported
    authenticatorSelection: {
      userVerification: "preferred", // Ensures user presence
      requireResidentKey: true,
    },
    attestation: "direct",
  },
};

// For authentication
const getOptions = {
  publicKey: {
    challenge: challenge, // From API URL - already base64 encoded
    userVerification: "preferred", // Ensures user presence
    timeout: 60000,
  },
};

​

Error Handling

​

Common Errors

​

Registration Failure Recovery

If local passkey creation succeeds but submission fails:

• The passkey exists locally but has no associated on-chain account
• Solution: Re-request a new URL with action: "create" and submit again
• The existing local passkey will work with the new challenge
• No need to recreate the local passkey

​

Best Practices

​

Challenge Handling

• Parse challenge from URL parameters
• Use challenge directly - it’s already base64 encoded
• Never re-encode the challenge
• Complete WebAuthn ceremony within 60 seconds of URL generation

​

Security

• Validate all inputs
• Use HTTPS for all communications
• Implement proper CORS policies
• Never expose API keys in client-side code
• Store session keys securely on client side

​

Implementation

• Generate unique session keys for each authentication
• Implement comprehensive error handling
• Provide user-friendly error messages
• Use clear, recognizable app names
• Provide loading states during authentication

​

Getting Started

1. Review Requirements: Ensure you have WebAuthn expertise and need company URL branding
2. Set Up Domain: Configure your company domain for passkey flows
3. Implement WebAuthn: Build custom UI following the requirements above
4. Test on Devnet: Thoroughly test your implementation before production
5. Handle Errors: Implement robust error handling and recovery

For most applications, consider using the hosted UI approach instead, which handles all this complexity for you.