# 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 Blockin 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.

```json
{
  "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
   * Blockin 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