Custom Domain

​

When to Use Advanced Integration

• 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

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

• 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

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

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

// 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

• 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