API Authentication

# Create API key via CLI
$ hyperfold auth create-key --name="Production API" --scopes=catalog:read,catalog:write

API KEY CREATED
  Name:         Production API
  Key:          hf_live_abc123xyz...
  Scopes:       catalog:read, catalog:write
  Created:      2025-01-20T10:00:00Z
⚠ Save this key securely - it won't be shown again.

# List API keys
$ hyperfold auth list-keys

API KEYS
NAME              SCOPES                      LAST USED        STATUS
Production API    catalog:read,write          2 min ago        active
CI/CD Pipeline    agents:deploy               1 hour ago       active
Analytics         analytics:read              3 days ago       active

# Revoke API key
$ hyperfold auth revoke-key hf_live_abc123xyz
✓ API key revoked

# OAuth 2.0 Authorization Code Flow
# Step 1: Redirect user to authorization URL
https://auth.hyperfold.io/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=catalog:read%20agents:read&
  state=random_state_string
# Step 2: Exchange code for tokens
curl -X POST https://auth.hyperfold.io/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_CALLBACK" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "redirect_uri=https://yourapp.com/callback"
# Response
{
  "access_token": "hf_oauth_xyz...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "hf_refresh_abc...",
  "scope": "catalog:read agents:read"
}
# Step 3: Use access token
curl -X GET https://api.hyperfold.io/v1/catalog/products \
  -H "Authorization: Bearer hf_oauth_xyz..."
# Step 4: Refresh token when expired
curl -X POST https://auth.hyperfold.io/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=hf_refresh_abc..." \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

# Service Account authentication (for server-to-server)
# Download service account key from console
$ hyperfold auth create-service-account \
  --name="Backend Service" \
  --scopes=full_access \
  --output=service-account.json
# service-account.json contents:
{
  "type": "service_account",
  "project_id": "proj_acme",
  "private_key_id": "key_123",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
  "client_email": "backend@proj_acme.hyperfold.io",
  "client_id": "sa_xyz789"
}
# Generate JWT and exchange for access token
import jwt
import time
import requests
def get_access_token(service_account_path):
    with open(service_account_path) as f:
        sa = json.load(f)
    now = int(time.time())
    payload = {
        "iss": sa["client_email"],
        "sub": sa["client_email"],
        "aud": "https://api.hyperfold.io",
        "iat": now,
        "exp": now + 3600
    }
    token = jwt.encode(payload, sa["private_key"], algorithm="RS256")
    response = requests.post(
        "https://auth.hyperfold.io/token",
        data={
            "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
            "assertion": token
        }
    )
    return response.json()["access_token"]

# Available OAuth scopes
SCOPE                    DESCRIPTION
─────────────────────────────────────────────────────────────
catalog:read             Read product catalog
catalog:write            Create/update products
agents:read              View agent configurations
agents:deploy            Deploy and manage agents
payments:read            View payment data
payments:write           Process payments
analytics:read           Access analytics data
integrations:read        View integration configs
integrations:write       Manage integrations
workflows:read           View workflow definitions
workflows:write          Create/modify workflows
admin                    Full administrative access

# Scope format for requests
scope=catalog:read%20catalog:write%20agents:read