Authentication

// Creating a restricted key via API
const restrictedKey = await stateset.apiKeys.create({
  name: 'Read-only Orders Key',
  permissions: [
    'orders:read',
    'customers:read'
  ],
  expires_at: '2024-12-31T23:59:59Z'
});

{
  "header": {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "key_id_123"
  },
  "payload": {
    "sub": "user_123",
    "org_id": "org_456",
    "role": "admin",
    "permissions": ["orders:*", "customers:*"],
    "iat": 1704067200,
    "exp": 1704070800,
    "iss": "https://api.stateset.com"
  },
  "signature": "..."
}

# GraphQL endpoint
https://api.stateset.com/graphql

# Required headers
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-org-id": "org_123",
    "x-hasura-user-id": "user_456",
    "x-hasura-default-role": "operator",
    "x-hasura-allowed-roles": ["viewer", "operator", "manager"],
    "x-hasura-team-id": "team_789",
    "x-hasura-permissions": [
      "orders:read",
      "orders:write",
      "customers:read"
    ]
  },
  "iat": 1704067200,
  "exp": 1704070800
}

// Middleware for permission checking
function requirePermission(permission) {
  return (req, res, next) => {
    const token = req.headers.authorization?.split(' ')[1];
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    
    const claims = decoded['https://hasura.io/jwt/claims'];
    const permissions = claims['x-hasura-permissions'] || [];
    
    if (!permissions.includes(permission)) {
      return res.status(403).json({
        error: 'INSUFFICIENT_PERMISSIONS',
        message: `Missing required permission: ${permission}`
      });
    }
    
    req.user = {
      id: claims['x-hasura-user-id'],
      org_id: claims['x-hasura-org-id'],
      role: claims['x-hasura-default-role'],
      permissions
    };
    
    next();
  };
}

// Usage
app.post('/api/orders', 
  requirePermission('orders:write'), 
  createOrderHandler
);

const crypto = require('crypto');

class WebhookVerifier {
  constructor(secret) {
    this.secret = secret;
  }
  
  verify(payload, signature) {
    // Parse signature header
    const elements = signature.split(' ');
    const timestamp = elements.find(e => e.startsWith('t=')).slice(2);
    const signatures = elements
      .filter(e => e.startsWith('v1='))
      .map(e => e.slice(3));
    
    // Check timestamp (5 minute tolerance)
    const currentTime = Math.floor(Date.now() / 1000);
    if (currentTime - parseInt(timestamp) > 300) {
      throw new Error('Webhook timestamp expired');
    }
    
    // Compute expected signature
    const signedPayload = `${timestamp}.${payload}`;
    const expectedSig = crypto
      .createHmac('sha256', this.secret)
      .update(signedPayload)
      .digest('hex');
    
    // Timing-safe comparison
    const valid = signatures.some(sig => 
      crypto.timingSafeEqual(
        Buffer.from(sig),
        Buffer.from(expectedSig)
      )
    );
    
    if (!valid) {
      throw new Error('Invalid webhook signature');
    }
    
    return JSON.parse(payload);
  }
}

// Express middleware
const webhookAuth = (req, res, next) => {
  const verifier = new WebhookVerifier(process.env.WEBHOOK_SECRET);
  
  try {
    req.body = verifier.verify(
      req.rawBody,
      req.headers['stateset-signature']
    );
    next();
  } catch (error) {
    res.status(401).json({ error: 'Webhook verification failed' });
  }
};

import { useState, useEffect } from 'react';
import { useAuth } from '@clerk/nextjs';

/**
 * Custom hook for authenticated Stateset API calls
 */
export const useStatesetAPI = () => {
  const { getToken, isSignedIn } = useAuth();
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  
  const apiCall = async (endpoint, options = {}) => {
    if (!isSignedIn) {
      throw new Error('User not authenticated');
    }
    
    setLoading(true);
    setError(null);
    
    try {
      const token = await getToken({ template: 'stateset' });
      
      const response = await fetch(`https://api.stateset.com/v1${endpoint}`, {
        ...options,
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      });
      
      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || 'API request failed');
      }
      
      const data = await response.json();
      return data;
      
    } catch (err) {
      setError(err);
      throw err;
    } finally {
      setLoading(false);
    }
  };
  
  return { apiCall, loading, error };
};

// Usage
function OrderList() {
  const { apiCall } = useStatesetAPI();
  const [orders, setOrders] = useState([]);
  
  useEffect(() => {
    apiCall('/orders')
      .then(data => setOrders(data.orders))
      .catch(console.error);
  }, []);
  
  return (
    <div>
      {orders.map(order => (
        <OrderCard key={order.id} order={order} />
      ))}
    </div>
  );
}

import os
import time
import requests
from typing import Optional, Dict, Any
from functools import wraps

class StatesetAuth:
    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key or os.getenv('STATESET_API_KEY')
        self.base_url = 'https://api.stateset.com/v1'
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {self.api_key}',
            'Content-Type': 'application/json'
        })
    
    def validate_key(self) -> bool:
        """Validate API key is active"""
        try:
            response = self.session.get(f'{self.base_url}/auth/validate')
            return response.status_code == 200
        except:
            return False
    
    def with_retry(self, max_retries: int = 3):
        """Decorator for automatic retry with exponential backoff"""
        def decorator(func):
            @wraps(func)
            def wrapper(*args, **kwargs):
                for attempt in range(max_retries):
                    try:
                        return func(*args, **kwargs)
                    except requests.exceptions.RequestException as e:
                        if attempt == max_retries - 1:
                            raise
                        wait_time = 2 ** attempt
                        time.sleep(wait_time)
                return None
            return wrapper
        return decorator
    
    @with_retry(max_retries=3)
    def api_request(
        self,
        method: str,
        endpoint: str,
        data: Optional[Dict[Any, Any]] = None
    ) -> Dict[Any, Any]:
        """Make authenticated API request"""
        url = f'{self.base_url}{endpoint}'
        response = self.session.request(method, url, json=data)
        response.raise_for_status()
        return response.json()

# Usage
auth = StatesetAuth()
if auth.validate_key():
    orders = auth.api_request('GET', '/orders')
    print(f"Found {len(orders['data'])} orders")

# Test API key validity
curl -I https://api.stateset.com/v1/auth/validate \
  -H "Authorization: Bearer YOUR_API_KEY"

# Check key permissions
curl https://api.stateset.com/v1/auth/permissions \
  -H "Authorization: Bearer YOUR_API_KEY"