> ## Documentation Index
> Fetch the complete documentation index at: https://podium.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API key authentication, subscription tiers, rate limiting, key management, and public endpoint access

## API Key Authentication

All authenticated requests require a Bearer token in the `Authorization` header:

```bash theme={null}
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](https://app.podium.build/onboarding):

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**.

<Warning>
  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.
</Warning>

### Key Management

From the [API Keys dashboard](https://app.podium.build/dashboard/settings/api-keys), 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "status": 403,
  "error": "Endpoint not available on your current plan",
  "requiredTier": "PRO"
}
```

Upgrade your tier from the [Dashboard](https://app.podium.build/dashboard/settings/subscription) 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 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                                                               |

<Warning>
  Public endpoints still enforce rate limiting by IP address. Abuse triggers automatic throttling.
</Warning>

## 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:

```json theme={null}
// 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"
}
```