Authentication

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:

Extracts the key from the Authorization header
Validates the key prefix matches the expected environment (podium_test_ or podium_live_)
SHA-256 hashes the key and looks it up in the database
Returns the associated organization context (ID, settings, subscription tier)
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:

Sign up with email, Google, or a crypto wallet
Create an organization during onboarding
Choose a subscription tier (see pricing below)
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:

Action	Description
Create	Generate a new key (up to your tier’s limit)
Rotate	Generate a replacement key. The old key remains valid for 30 minutes, giving you time to update your application.
Enable/Disable	Toggle a key without deleting it
Delete	Permanently 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 Prefix	Environment	Base URL
`podium_test_`	Staging	`https://podium-staging.up.railway.app/api/v1`
`podium_live_`	Production	`https://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.

Tier	Price	Requests/Month	Rate Limit/Second	Max API Keys	Endpoint Access
Builder	Free	10,000	5	1	Core commerce endpoints
Growth	$99/mo	100,000	20	5	+ Campaigns, NFTs, search
Pro	$499/mo	1,000,000	100	10	+ Enrichment, agentic, analytics
Enterprise	Custom	Unlimited	Custom	Unlimited	Full 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:

Enable x402 payments for your organization
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 Pattern	Purpose
`/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/callback`	Shippo OAuth callback
`/shopify/callback`	Shopify 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

Role	Capabilities
`ADMIN`	Full organization management, API key CRUD, tier management
`CAMPAIGN_ADMIN`	Campaign creation, publishing, and moderation

Creator Roles

Role	Capabilities
`PUBLISHER`	Product 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"
}

Getting Started

Platform

Authentication

API Key Authentication

Getting Your API Key

Key Management

Environments

Subscription Tiers

Rate Limiting

Access Control

x402 Payment Configuration

Public Endpoints

Role-Based Access

User Roles

Creator Roles

Error Responses

​API Key Authentication

​Getting Your API Key

​Key Management

​Environments

​Subscription Tiers

​Rate Limiting

​Access Control

​x402 Payment Configuration

​Public Endpoints

​Role-Based Access

​User Roles

​Creator Roles

​Error Responses

API Key Authentication

Getting Your API Key

Key Management

Environments

Subscription Tiers

Rate Limiting

Access Control

x402 Payment Configuration

Public Endpoints

Role-Based Access

User Roles

Creator Roles

Error Responses