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

```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
   * 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbadges.io/token-standard/skills/bb-402.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.