Skip to main content

​
API Key Authentication

All authenticated requests require a Bearer token in the Authorization header: 
Authorization: Bearer podium_live_abc123...
API keys are scoped to a single organization. When the platform receives a request:
  1. Extracts the key from the Authorization header
  2. Validates the key prefix matches the expected environment (podium_test_ or podium_live_)
  3. SHA-256 hashes the key and looks it up in the database
  4. Returns the associated organization context (ID, settings, subscription tier)
  5. Caches the result with a jittered TTL (60–150 seconds)
Failed lookups are also cached (15 seconds) to prevent brute-force probing from hitting the database.

​
Getting Your API Key

API keys are self-service through the Podium Developer Portal:
  1. Sign up with email, Google, or a crypto wallet
  2. Create an organization during onboarding
  3. Choose a subscription tier (see pricing below)
  4. Generate your first key — the onboarding flow creates one automatically
Additional keys can be created from Dashboard > Settings > API Keys.
Your full API key is only shown once at creation. Copy it immediately and store it securely. The dashboard only displays the key prefix after creation.

​
Key Management

From the API Keys dashboard, you can:
ActionDescription
CreateGenerate a new key (up to your tier’s limit)
RotateGenerate a replacement key. The old key remains valid for 30 minutes, giving you time to update your application.
Enable/DisableToggle a key without deleting it
DeletePermanently revoke a key
Key changes propagate immediately. Cached keys expire within 15–150 seconds. Immediate invalidation is triggered via an api-key-changed event that purges the cache.

​
Environments

Key PrefixEnvironmentBase URL
podium_test_Staginghttps://podium-staging.up.railway.app/api/v1
podium_live_Productionhttps://api.podium.build/api/v1
The TypeScript SDK auto-detects the environment from the key prefix and routes to the correct base URL.

​
Subscription Tiers

Each organization has a subscription tier that controls rate limits, request quotas, and endpoint access. Manage your subscription from Dashboard > Settings > Subscription.
TierPriceRequests/MonthRate Limit/SecondMax API KeysEndpoint Access
BuilderFree10,00052Core commerce endpoints
Growth$99/mo100,000205+ Campaigns, NFTs, search
Pro$499/mo1,000,0005020+ Enrichment, agentic, analytics
EnterpriseCustomUnlimitedCustomUnlimitedFull platform access
Growth and Pro tiers support overage billing for requests beyond the monthly quota.

​
Rate Limiting

Rate limits are enforced per-organization using a sliding window. When exceeded, the API returns: 
{
  "status": 429,
  "error": "Rate limit exceeded",
  "retryAfter": 1.2
}
The Retry-After header indicates seconds until the next allowed request.

​
Access Control

The access control middleware checks each endpoint against the organization’s tier. If an endpoint is blocked for the current tier: 
{
  "status": 403,
  "error": "Endpoint not available on your current plan",
  "requiredTier": "PRO"
}
Upgrade your tier from the Dashboard to unlock additional API surface.

​
x402 Payment Configuration

To accept USDC payments via the x402 protocol, configure your receiving wallet from Dashboard > Settings > x402 Payments:
  1. Enable x402 payments for your organization
  2. Set your USDC receiving address (on Base)
Once configured, your organization’s endpoints can accept x402 payment headers, and companion/agentic orders can settle in USDC.

​
Public Endpoints

Some endpoints are accessible without authentication for specific use cases:
Path PatternPurpose
/agentic/*Agentic Commerce Protocol — AI agents discover products and create checkout sessions
/webhooks/*Inbound webhooks from Stripe, Shopify, Privy, and internal events
/solver/*Solver discovery for the Task Pool system
/shippo/callbackShippo OAuth callback
/shopify/callbackShopify OAuth callback
Public endpoints still enforce rate limiting by IP address. Abuse triggers automatic throttling.

​
Role-Based Access

Within an organization, users and creators can have roles that gate specific operations:

​
User Roles

RoleCapabilities
ADMINFull organization management, API key CRUD, tier management
CAMPAIGN_ADMINCampaign creation, publishing, and moderation

​
Creator Roles

RoleCapabilities
PUBLISHERProduct publishing, order management, payout access
Roles are checked by ensureUserHasRole() and ensureCreatorHasRole() guards within route handlers.

​
Error Responses

Authentication failures return standard error shapes: 
// Missing or malformed key
{
  "status": 401,
  "error": "Invalid or missing API key"
}

// Expired key
{
  "status": 401,
  "error": "API key has expired"
}

// Insufficient tier
{
  "status": 403,
  "error": "Endpoint not available on your current plan"
}