Developer Integration Guide

What is a Stamp?

A Human Passport Stamp is a verifiable credential that proves a user has completed identity verification or demonstrated specific onchain/offchain activity. Each Stamp consists of:

• Platform: The service/protocol providing verification (e.g., Discord, GitHub, Binance)
• Provider(s): Specific verification types within a platform (e.g., "Discord Account", "GitHub >30 commits")
• Verification Logic: Backend code that validates user claims
• UI Integration: Frontend components for user interaction

Architecture Overview

┌─────────────────┬─────────────────┬─────────────────┐
│   Frontend      │    Backend      │   Integration   │
│   (App)         │    (IAM)        │   (Platforms)   │
├─────────────────┼─────────────────┼─────────────────┤
│ • User Interface│ • Verification  │ • Platform Impl │
│ • OAuth Popups  │ • Credential    │ • Provider Impl │
│ • Wallet Connect│   Issuance      │ • Configuration │
│ • Form Handling │ • Error Handling│ • Tests         │
└─────────────────┴─────────────────┴─────────────────┘

Key Components:

• App-Bindings: Frontend platform implementation (user flows, OAuth, wallet connection)
• Providers: Backend verification logic (API calls, onchain checks, credential issuance)
• Providers-config: UI metadata, user guidance, display configuration
• Integration: Registration with core system (platforms.ts, types, app config)

Integration Patterns

Human Passport supports four main integration patterns:

1. OAuth Integration

Best for: Social platforms, web services with OAuth APIs
Examples: Discord, Google, GitHub, LinkedIn
Flow: User clicks → OAuth popup → Authorization → Token exchange → API verification → Credential issued

2. Onchain Verification

Best for: Blockchain-based verification, token ownership, onchain activity
Examples: Binance BABT, ETH balance, NFT ownership
Flow: User connects wallet → Query blockchain/contract → Verify conditions → Credential issued

3. Custom API Integration

Best for: Proprietary verification systems, complex workflows
Examples: Guild.xyz, custom KYC providers
Flow: Custom authentication → API calls to your service → Verification logic → Credential issued

4. Wallet Signature

Best for: Proof of address ownership, simple onchain verification
Examples: Message signing, proof of control
Flow: User connects wallet → Sign message → Verify signature → Credential issued

File Structure Requirements

Every Stamp integration requires the following directory structure:

platforms/src/YourPlatform/
├── index.ts                    # Main exports (REQUIRED)
├── App-Bindings.tsx           # Frontend platform class (REQUIRED)
├── Providers-config.ts        # UI config & metadata (REQUIRED)
├── Providers/                 
│   ├── index.ts              # Provider exports (REQUIRED)
│   └── yourProvider.ts       # Verification logic (REQUIRED)
└── __tests__/                
    └── yourProvider.test.ts  # Test suite (REQUIRED)

Required Assets

app/public/assets/
└── yourPlatformIcon.svg       # Platform icon (REQUIRED)

Core Development Steps

Environment Configuration

Required Environment Variables

All Stamp integrations need appropriate environment variables:

# OAuth Configuration (for OAuth patterns)
NEXT_PUBLIC_YOURPLATFORM_CLIENT_ID=your_client_id
YOURPLATFORM_CLIENT_SECRET=your_client_secret  
NEXT_PUBLIC_YOURPLATFORM_CALLBACK=callback_url
 
# Feature Flag (optional, for gradual rollout)
NEXT_PUBLIC_FF_YOURPLATFORM_STAMP=on

OAuth Setup

For OAuth integrations, configure your application with these redirect URIs:

• Development: http://localhost:3000/auth/yourplatform/callback
• Staging: https://staging.passport.xyz/auth/yourplatform/callback
• Production: https://passport.xyz/auth/yourplatform/callback

UI Configuration (Post-Reskin)

The July 2024 reskin introduced new required metadata fields in PlatformDetails:

Required Fields

• timeToGet: Estimated completion time (e.g., "5 minutes", "10 minutes")
• price: Cost information (e.g., "Free", "$5 + gas fees")
• guide: Structured user guidance with two types:
  • steps: Sequential instructions with optional action buttons
  • list: Requirements, warnings, or considerations

Example Configuration

export const PlatformDetails: PlatformSpec = {
  icon: "./assets/yourPlatformIcon.svg",
  platform: "YourPlatform",
  name: "Your Platform Name",
  description: "Brief description of verification type",
  connectMessage: "Verify Account",
  website: "https://www.yourplatform.com",
  timeToGet: "5 minutes", // NEW REQUIRED FIELD
  price: "Free",         // NEW REQUIRED FIELD
  
  // NEW REQUIRED FIELD: Detailed user guidance
  guide: [
    {
      type: "steps",
      title: "How to Verify",
      items: [
        {
          title: "Step 1: Create Account",
          description: "Sign up and verify your email",
          actions: [
            {
              label: "Sign Up Now",
              href: "https://www.yourplatform.com/signup",
            },
          ],
        },
        // ... more steps
      ],
    },
    {
      type: "list", 
      title: "Requirements",
      items: [
        "Valid email address required",
        "Account must be at least 30 days old",
        "Some regions may be restricted",
      ],
    },
  ],
};

Next Steps

• Review specific Implementation Patterns for your use case
• Check out complete Code Examples
• Learn about Testing & Security requirements
• Use the Submission Checklist when ready to submit

Support

For technical questions during development:

• Review the troubleshooting guide
• Check existing implementations in the repository
• Contact the Human Passport team for complex integration questions