# GFAVIP Wallet & PowerLobster SSO Integration Guide

This document provides instructions for AI agents to authenticate with the GFAVIP ecosystem using PowerLobster Identity.

## Overview

The GFAVIP Wallet (wallet.gfavip.com) serves as the central authentication and wallet system for the GFAVIP ecosystem. AI agents can use their PowerLobster API key to obtain a GFAVIP SSO token, granting access to all ecosystem apps (Wallet, DailySchools, HandyCon, Checkout, Tickets, etc.).

## Authentication (The "Happy Path")

To get a GFAVIP SSO token, perform this exact POST request:

**Endpoint:** `POST https://wallet.gfavip.com/api/auth/powerlobster`
**Headers:** `Content-Type: application/json`
**Body:**
```json
{
  "token": "YOUR_POWERLOBSTER_IDENTITY_TOKEN"
}
```

**Returns:**
```json
{
  "status": "success",
  "sso_token": "gfavip-session-..."
}
```

## Authentication Flow

1.  **Get PowerLobster Identity Token**
    *   **Endpoint:** `POST https://powerlobster.com/api/agent/identity-token`
    *   **Headers:** `Authorization: Bearer <YOUR_POWERLOBSTER_API_KEY>`
    *   **Response:** `{"identity_token": "..."}`

2.  **Exchange for GFAVIP SSO Token**
    *   **Endpoint:** `POST https://wallet.gfavip.com/api/auth/powerlobster`
    *   **Headers:** `Content-Type: application/json`
    *   **Body:** `{"token": "<IDENTITY_TOKEN_FROM_STEP_1>"}`
    *   **Response:**
        ```json
        {
          "status": "success",
          "sso_token": "gfavip-session-...",
          "expires_at": "2024-...",
          "user": { ... }
        }
        ```
    *   **Note:** If this is your first time, an account will be automatically created and linked to your PowerLobster identity.

3.  **Access Ecosystem Apps**
    *   Use the `sso_token` as a Bearer token in the Authorization header.
    *   **Header:** `Authorization: Bearer <SSO_TOKEN>`
    *   **Validity:** The token is valid for 30 days. Cache and reuse it.

## Example Usage (cURL)

```bash
# 1. Get Identity Token
PL_TOKEN=$(curl -s -X POST https://powerlobster.com/api/agent/identity-token \
  -H "Authorization: Bearer YOUR_PL_API_KEY" | jq -r '.identity_token')

# 2. Get SSO Token
SSO_TOKEN=$(curl -s -X POST https://wallet.gfavip.com/api/auth/powerlobster \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"$PL_TOKEN\"}" | jq -r '.sso_token')

# 3. Make API Call (e.g., Validate Token)
curl https://wallet.gfavip.com/api/auth/validate \
  -H "Authorization: Bearer $SSO_TOKEN"
```

## Supported Applications

The SSO token is valid across:
*   `wallet.gfavip.com`
*   `checkout.gfavip.com`
*   `tickets.gfavip.com`
*   Any other GFAVIP ecosystem app.

For full documentation on PowerLobster SSO, visit: https://wallet.gfavip.com/skill_powerlobster.md

## For App Developers

If you are integrating GFAVIP SSO into your application, please read our [Guide to Enabling Headless / AI Agent Access](https://wallet.gfavip.com/headless_sso.md).