Predikt
Get API Key

Authentication

All API requests require authentication using an API key.

API Key Authentication

Include your API key in the Authorization header with every request using the Bearer scheme.

Header Format
Authorization: Bearer pk_live_your_api_key

You can also pass the API key directly without the Bearer prefix:

Alternative
Authorization: pk_live_your_api_key

API Key Format

API keys follow a specific format for easy identification:

pk_live_[32 character random string]
  • pk_ indicates this is a Predikt API key
  • live_ indicates this is a production key

API Key Permissions

When creating an API key, you can specify which endpoints it can access:

PermissionEndpointsDescription
price/price/*Access price data endpoints
ai/ai/*Access AI resolution endpoints
batch/price/batchAccess batch price requests
historical/historical/*Access historical data
markets/markets/*Access market data
websocket/wsConnect to WebSocket for real-time data
scheduled*/schedule, */scheduled/*Create and manage scheduled jobs

By default, new API keys have price and ai permissions.

Authentication Errors

Response (401)
{
  "error": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}

The API key is missing, invalid, or has been revoked.

Response (403)
{
  "error": "Insufficient permissions for this endpoint",
  "code": "INSUFFICIENT_PERMISSIONS",
  "required": ["ai"]
}

The API key does not have the required permissions for this endpoint.

Response (402)
{
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_BALANCE",
  "balanceUsd": "0.01",
  "requiredUsd": "0.02"
}

Your account balance is too low to complete this request.

Key Expiration

You can set an expiration date when creating or editing an API key. Expired keys are automatically rejected.

  • Keys without an expiration date never expire
  • You can update or remove expiration dates at any time
  • Expired keys return a 401 error with code API_KEY_EXPIRED

Key Rotation

Rotate your API keys periodically for enhanced security. When you rotate a key:

  • A new key is generated with the same permissions and settings
  • The old key remains valid for a 60-minute grace period
  • After the grace period, the old key automatically expires

Custom Rate Limits

Set custom rate limits on individual API keys to control request frequency. Custom limits must be at or below your account tier's maximum.

TierMax Rate LimitWindow Range
Standard1–60 requests60–3600 seconds
Pro1–300 requests60–3600 seconds
Enterprise1–1000 requests60–3600 seconds
  • Both customRateLimit and customRateLimitWindow must be set together
  • If not set, the key uses your account tier's default rate limit
  • Set to null to remove custom limits and revert to tier defaults
Response (429)
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "limit": 60,
  "windowSeconds": 60,
  "retryAfter": 45
}

Returned when the key's rate limit is exceeded. Wait for retryAfter seconds before retrying.

Usage Quotas

Set daily and monthly request quotas on individual API keys to control total usage. Quotas are measured in request count, not dollar amounts.

  • dailyQuota — Maximum requests per day (resets at midnight UTC)
  • monthlyQuota — Maximum requests per month (resets on the 1st at midnight UTC)
  • Set to null for unlimited requests (default)
  • Current usage is tracked via currentDayUsage and currentMonthUsage in the key response
Response (403)
{
  "error": "Daily quota exceeded for this API key",
  "code": "QUOTA_EXCEEDED",
  "quotaType": "daily",
  "limit": 10000,
  "usage": 10000
}

Returned when the key's daily or monthly quota is exceeded. Wait for the quota to reset or increase the limit.

IP Whitelisting

Restrict API key usage to specific IP addresses or CIDR ranges for enhanced security.

Supported formats:

  • IPv4: 192.168.1.1
  • IPv4 CIDR: 192.168.1.0/24
  • IPv6: 2001:db8::1
  • IPv6 CIDR: 2001:db8::/32
Response (403)
{
  "error": "IP address not allowed for this API key",
  "code": "IP_NOT_ALLOWED",
  "clientIp": "203.0.113.50"
}

Returned when a request comes from an IP not in the whitelist.

Origin Restrictions

For browser-based API keys, you can restrict usage to specific origins (domains).

Supported formats:

  • Exact: https://myapp.com
  • Wildcard: https://*.myapp.com
Response (403)
{
  "error": "Origin not allowed for this API key",
  "code": "ORIGIN_NOT_ALLOWED",
  "origin": "https://unauthorized-site.com"
}

API Key Limits

The number of API keys and their capabilities depend on your account tier:

TierMax KeysMax IPsMax Rate LimitQuotas
Standard32060/minSupported
Pro1020300/minSupported
EnterpriseUnlimited201000/minSupported

Per-key custom rate limits can be set up to your tier's maximum. Daily and monthly quotas can be set on any key regardless of tier.

Security Best Practices

  • Never expose API keys in client-side codeAlways make API calls from your server, not from browsers or mobile apps.
  • Use environment variablesStore API keys in environment variables, not in your codebase.
  • Use minimal permissionsOnly grant the permissions your application actually needs.
  • Enable IP whitelistingRestrict your API keys to known server IP addresses.
  • Set expiration datesUse expiring keys and rotate them regularly for enhanced security.
  • Rotate keys regularlyUse the key rotation feature to seamlessly replace keys with a grace period.
  • Set usage quotasUse daily and monthly quotas to prevent unexpected usage spikes and control costs.

Next Steps