An integration guide for the GFAVIP ecosystem.

Overview

The GFAVIP Chapters API enables cross-app integration within the GFAVIP ecosystem. This API allows other applications (like learning.gfavip.com) to verify chapter memberships, apply special pricing, and provide exclusive benefits to chapter members.

Authentication

All API requests use GFAVIP Simple SSO tokens for authentication. No API keys are required. Tokens follow the format: gfavip-session-{userId}

Authentication Header

Authorization: Bearer {token}

Users authenticate through wallet.gfavip.com with the service=chapters parameter. After successful SSO callback, tokens are stored in localStorage and used for all API requests.

Core Endpoints

Get User's Chapter Memberships

Returns all chapter memberships for the authenticated user. This is the primary endpoint for verifying membership status and applying benefits in external applications.

Request Headers

Authorization: Bearer {token}

Response Fields

Field	Type	Description
chapter_id	string (UUID)	Unique chapter identifier
chapter_name	string	Chapter name (e.g., "GFA Nexus")
chapter_slug	string	URL-friendly slug (e.g., "gfa-nexus")
role	string	User's role: "member" or "leader"
status	string	Membership status: "active", "pending", "expired", "banned"
join_date	string (ISO 8601)	When user joined the chapter
renew_date	string (ISO 8601) or null	When membership was last renewed (null if never renewed)
learning_discount	number	Discount percentage for learning platform (0-100)

Example Response

[
  {
    "chapter_id": "550e8400-e29b-41d4-a716-446655440000",
    "chapter_name": "GFA Nexus",
    "chapter_slug": "gfa-nexus",
    "role": "member",
    "status": "active",
    "join_date": "2024-01-15T10:30:00Z",
    "renew_date": "2024-10-15T10:30:00Z",
    "learning_discount": 50
  },
  {
    "chapter_id": "660e8400-e29b-41d4-a716-446655440001",
    "chapter_name": "GFA Chronos",
    "chapter_slug": "gfa-chronos",
    "role": "leader",
    "status": "active",
    "join_date": "2024-03-20T14:00:00Z",
    "renew_date": null,
    "learning_discount": 50
  }
]

Get All Public Chapters

Returns a list of all publicly visible chapters. No authentication required. Useful for displaying available chapters in external apps.

Query Parameters

Parameter	Type	Description
search	string	Optional. Filter chapters by name or description

Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "gfa-nexus",
    "name": "GFA Nexus",
    "description": "Global chapter for blockchain entrepreneurs",
    "image_url": "https://storage.googleapis.com/...",
    "member_count": 42,
    "leader": {
      "id": "...",
      "username": "john_doe",
      "email": "john@example.com"
    },
    "configs": {
      "price_usd": 200,
      "recurring": true,
      "learning_discount": 50,
      "min_members": 10,
      "min_events": 6
    }
  }
]

Integration Use Cases

1. Apply Learning Discount

When a user visits learning.gfavip.com, call /api/chapters/memberships to check if they have active chapter memberships. For each active membership, apply the learning_discount percentage to course pricing.

Implementation Steps:

1. User authenticates with GFAVIP SSO
2. Learning platform calls GET /api/chapters/memberships with user's token
3. Check for memberships with status: "active"
4. Apply the highest learning_discount from all active memberships
5. Display discounted pricing to the user

2. Chapter-Exclusive Content

Grant access to exclusive courses or content based on chapter membership. Use chapter_slug to identify which chapter benefits to apply.

3. Member Verification

Verify that a user is an active member of a specific chapter before granting access to chapter-specific resources or benefits.

Example Verification Logic:

// Check if user is active member of GFA Nexus
const memberships = await fetch('/api/chapters/memberships', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const data = await memberships.json();

const isNexusMember = data.some(m => 
  m.chapter_slug === 'gfa-nexus' && 
  m.status === 'active'
);

if (isNexusMember) {
  // Apply 50% discount or grant exclusive access
  const discount = data.find(m => m.chapter_slug === 'gfa-nexus').learning_discount;
}

Membership Status Values

Status	Description	Apply Benefits?
active	Membership is paid and current	✅ Yes
pending	Payment initiated but not yet confirmed	❌ No
expired	Membership has expired (payment failed or not renewed)	❌ No
banned	User has been banned from the chapter	❌ No

Error Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing authentication token
404	Resource not found
500	Internal server error

Rate Limiting

Currently, there are no rate limits enforced. Please use the API responsibly and cache membership data when appropriate to minimize unnecessary requests.

Support

For integration assistance or questions, please contact the GFAVIP development team.