BB-402 Token-Gated Access

Token-gated access protocol where ownership of specific badges grants API/resource access

Category: Features

Summary

Protocol for token-gated access to APIs/resources using HTTP 402 Payment Required.

• Flow: client requests resource -> server returns 402 + required badge criteria -> client proves ownership -> server validates via BitBadges API

• ownershipRequirements: use $and for "must have all", $or for "must have any"

• mustOwnAmounts: { start: 1, end: 1 } = must own at least 1

• mustOwnAmounts: { start: 0, end: 0 } = must NOT own (exclusion)

• Tiered access: different token IDs = different access levels

• Time-bounded access: combine ownershipTimes with subscription tokens

• Server-side verification: BitBadgesApi.verifyOwnership() or SIWBB sign-in

Instructions

BB-402 Token-Gated Access Protocol

BB-402 is a protocol for token-gated access to APIs and digital resources. It uses HTTP 402 Payment Required responses to signal that badge ownership is needed.

How It Works

1. Client requests a protected resource

2. Server responds with HTTP 402 + required badge criteria

3. Client proves badge ownership (signs a challenge or presents proof)

4. Server validates ownership via BitBadges API and grants access

Design Patterns

Pattern 1: Simple Badge Gate

Require ownership of a specific badge to access a resource.

{
  "ownershipRequirements": {
    "$and": [{
      "assets": [{
        "chain": "BitBadges",
        "collectionId": 123,
        "assetIds": [{ "start": 1, "end": 1 }],
        "mustOwnAmounts": { "start": 1, "end": 1 },
        "ownershipTimes": []
      }]
    }]
  }
}

Pattern 2: Tiered Access

Different badge IDs = different access levels.

• Token ID 1 = Basic access

• Token ID 2 = Premium access

• Token ID 3 = Admin access

Pattern 3: Time-Bounded Access

Use ownershipTimes to restrict access to users who own the badge during specific periods. Combine with subscription tokens for recurring access.

Pattern 4: Multi-Collection Gate

Require badges from multiple collections using $and/$or logic.

Implementation Steps

1. Create the gate badge collection: Use NFT, fungible, or subscription patterns

2. Configure ownership requirements: Define what badges grant what access

3. Server integration: Use BitBadges API to verify ownership:

   • BitBadgesApi.verifyOwnership() for programmatic checks

   • SIWBB sign-in for session-based authentication

4. Client integration: Handle 402 responses, present proof of ownership

BB-402 Gotchas

• Badge ownership checks are point-in-time — consider caching strategies

• For subscription-based access, check ownershipTimes overlap with current time

• Use $and for "must have all", $or for "must have any"

• mustOwnAmounts: { start: 0, end: 0 } means must NOT own (exclusion)

• mustOwnAmounts: { start: 1, end: 1 } means must own at least 1