Skip to main content

API Keys

API keys provide programmatic access to Petal services.

Subscription Required

API access requires a Standard or Advanced subscription.

What Are API Keys For?​

API keys allow you to:

  • Validate subscriptions programmatically
  • Build integrations with your own software
  • Access Petal services from scripts and applications

Generating an API Key​

From the Website​

  1. Sign in at petal.tech/account
  2. Navigate to API Keys
  3. Click Generate API Key
  4. Copy and securely store your key

From the Desktop App​

  1. Open Petal Metrics
  2. Go to Settings → Account
  3. Scroll to API Key section
  4. Click Generate Key
  5. Copy and securely store your key
Save Your Key Immediately

For security, full API keys are only shown once. After you leave the page, only a prefix is displayed.

API Key Format​

API keys follow this format:

petal_live_XXXXXXXXXXXXXXXXXXXXXXXX
  • Prefix: petal_live_ indicates a production key
  • Suffix: 24 random characters (base64url encoded)
  • Total length: 35 characters

Using Your API Key​

Include your API key in the x-api-key header:

curl -X POST https://petal.tech/api/v1/metrics/api-key/validate \
  -H "Content-Type: application/json" \
  -d '{"api_key": "petal_live_your_key_here"}'

See the API Reference for available endpoints.

Key Security​

Best Practices​

  • Never commit API keys to version control
  • Use environment variables to store keys in your code
  • Rotate keys periodically
  • Revoke compromised keys immediately

Environment Variables​

# Set environment variable
export PETAL_API_KEY="petal_live_your_key_here"
# Use in Python
import os
api_key = os.environ.get('PETAL_API_KEY')
// Use in Node.js
const apiKey = process.env.PETAL_API_KEY;

Regenerating Your Key​

If your key is compromised or you want to rotate it:

  1. Go to petal.tech/account/api-keys
  2. Click Regenerate Key
  3. Confirm the action
  4. Update your applications with the new key
warning

Regenerating invalidates your old key immediately. Update all applications before regenerating.

Rate Limits​

API requests are rate limited:

EndpointLimit
/api/v1/metrics/api-key/validate120 requests/minute
/api/v1/license/*30 requests/minute
/api/v1/auth/login5 requests/minute
/api/v1/auth/signup3 requests/minute
Other endpoints60 requests/minute

If you exceed the limit, you'll receive a 429 Too Many Requests response with Retry-After header.

Troubleshooting​

"Invalid API key" (INVALID_API_KEY)​

  • Verify the key is correct (no extra spaces)
  • Ensure you're using the full key, not just the prefix
  • Check that your subscription includes API access
  • If you're a legacy customer, contact support@petal.tech

"Subscription has expired" (SUBSCRIPTION_EXPIRED)​

  • Your grandfathered API access period has ended
  • Purchase a Standard or Advanced plan at petal.tech/pricing
  • Your existing API key will work again once your subscription is active
  • See the Migration Guide for more details

"Subscription inactive" (SUBSCRIPTION_INACTIVE)​

  • Your account exists but you don't have an active subscription
  • Purchase a plan at petal.tech/pricing

"API access disabled" (API_ACCESS_DISABLED)​

"Rate limit exceeded"​

  • Wait before making more requests
  • Implement backoff in your application
  • Cache responses where possible

See Also​