Managing API Keys

API keys authenticate your applications when calling PrompTick agents. Learn how to create, manage, and secure them.

What are API Keys?

API keys are secret tokens that:

• ✅ Authenticate API requests to your agents
• ✅ Track usage and enforce rate limits
• ✅ Can be created, revoked, and rotated
• ✅ Are scoped to specific agents

Format: pk_live_1234567890abcdef...

Creating API Keys

Step 1: Navigate to Agent

1. Go to your project dashboard
2. Click Agents tab
3. Select the agent you want to create a key for

Step 2: Open API Keys Dialog

1. Click "API Keys" button
2. Click "Create New API Key"

Step 3: Configure the Key

Basic Settings

Name: Descriptive identifier

Examples:
- "Production Server"
- "Mobile App - iOS"
- "Testing Environment"

Rate Limits

Set usage limits to prevent abuse:

{
  requestsPerMinute: 100,
  requestsPerHour: 5000,
  requestsPerDay: 100000
}

Recommended Limits:

• Development: 10/min, 500/hour, 10K/day
• Production: 100/min, 5K/hour, 100K/day
• Enterprise: 1000/min, 50K/hour, 1M/day

Expiration

Never: Key never expires (less secure) 30 days: Good for temporary access 90 days: Recommended for production Custom: Set specific expiry date

Best Practice

Use expiring keys and rotate them regularly for better security.

Allowed Origins (Optional)

For web applications, restrict which domains can use this key:

https://app.example.com
https://admin.example.com

Leave empty to allow all origins.

Step 4: Create & Copy Key

1. Click "Create API Key"
2. Copy the key immediately!

pk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Important

API keys are shown only once. If you lose it, you must create a new one.

Using API Keys

Authentication Header

Include the API key in the Authorization header with the Bearer scheme:

curl -X POST https://api.promptick.ai/api/v1/agents/{agentId}/execute \
  -H "Authorization: Bearer pk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {...}}'

In Application Code

Node.js:

const headers = {
  Authorization: `Bearer ${process.env.PROMPTICK_API_KEY}`,
  'Content-Type': 'application/json',
};

Python:

headers = {
    'Authorization': f'Bearer {os.getenv("PROMPTICK_API_KEY")}',
    'Content-Type': 'application/json'
}

Security

Always store API keys in environment variables, never hardcode them!

Managing Existing Keys

View All Keys

1. Open agent
2. Click "API Keys"
3. See list of all keys with:
   • Name
   • Key prefix (last 8 characters)
   • Usage count
   • Last used date
   • Expiration date
   • Status (active/expired)

Revoke a Key

Immediately invalidate an API key:

1. Find the key in the list
2. Click "Revoke" (trash icon)
3. Confirm revocation
4. Key is immediately deactivated

When to Revoke

• Key was compromised or exposed
• Employee left company
• Changing environments
• Key no longer needed

Key Status Indicators

Status	Icon	Meaning
Active	🟢	Working normally
Expired	🔴	Past expiration date
Revoked	⛔	Manually disabled
Rate Limited	⚠️	Temporarily throttled

Security Best Practices

1. Use Environment Variables

Never hardcode API keys:

// ❌ DON'T DO THIS
const apiKey = 'pk_live_abc123...';

// ✅ DO THIS
const apiKey = process.env.PROMPTICK_API_KEY;

2. Rotate Keys Regularly

Create a rotation schedule:

• Critical apps: Every 30 days
• Production apps: Every 90 days
• Development: Every 180 days

Rotation Process:

1. Create new API key
2. Update applications with new key
3. Monitor for errors
4. Revoke old key after 24-48 hours

3. Use Separate Keys per Environment

Don't share keys across environments:

Development:   pk_live_dev_...
Staging:       pk_live_stg_...
Production:    pk_live_prod_...

4. Set Restrictive Rate Limits

Start with conservative limits and increase as needed:

{
  requestsPerMinute: 10,    // Start low
  requestsPerHour: 500,     // Monitor usage
  requestsPerDay: 10000     // Increase gradually
}

5. Monitor Usage

Regularly check:

• Total requests per key
• Error rates
• Unusual patterns
• Cost per key

6. Use CORS Restrictions

For web apps, whitelist specific origins:

Allowed Origins:
- https://app.mycompany.com
- https://admin.mycompany.com

7. Implement Key Fallback

Have backup keys ready:

const apiKeys = [
  process.env.PROMPTICK_API_KEY_PRIMARY,
  process.env.PROMPTICK_API_KEY_BACKUP,
];

async function makeRequest() {
  for (const key of apiKeys) {
    try {
      return await callAgent(key);
    } catch (error) {
      if (error.status === 401) continue; // Try next key
      throw error;
    }
  }
  throw new Error('All API keys failed');
}

Rate Limiting

How It Works

Each API key has three rate limit counters:

1. Per Minute: Rolling 60-second window
2. Per Hour: Rolling 60-minute window
3. Per Day: Calendar day (UTC)

When any limit is exceeded, the API returns:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 45,
  "rateLimits": {
    "requestsPerMinute": 100,
    "requestsPerHour": 5000,
    "requestsPerDay": 100000
  }
}

HTTP Status: 429 Too Many Requests

Handling Rate Limits

Exponential Backoff:

async function callAgentWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await callAgent();
    } catch (error) {
      if (error.status === 429) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Check Headers:

Response headers include rate limit info:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1638360000

Monitoring & Analytics

Per-Key Analytics

View detailed metrics for each API key:

1. Open agent
2. Click "API Keys"
3. Click on a key
4. View dashboard showing:
   • Requests over time
   • Success/error rates
   • Average latency
   • Cost per key

Usage Alerts

Set up notifications:

1. Go to agent settings
2. Click "Alerts"
3. Configure triggers:
   • High usage (>80% of limit)
   • Error rate spike (>5%)
   • Unusual patterns
   • Cost threshold

Troubleshooting

Invalid API Key Error

{
  "error": "Invalid or revoked API key",
  "message": "The provided API key is not valid for this agent"
}

Causes:

• ✅ Key was revoked
• ✅ Key expired
• ✅ Key for different agent
• ✅ Typo in key value

Solution: Create new API key

Rate Limit Exceeded

{
  "error": "Rate limit exceeded"
}

Solutions:

• Implement exponential backoff
• Increase rate limits in settings
• Use multiple keys with load balancing
• Upgrade plan

Unauthorized Access

{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header"
}

Causes:

• ❌ Missing Authorization header
• ❌ Wrong format (should be Bearer {key})
• ❌ Extra spaces or newlines

Solution: Check header format

Best Practices Checklist

✅ Store keys in environment variables ✅ Use separate keys per environment ✅ Set expiration dates (30-90 days) ✅ Configure rate limits appropriately ✅ Use CORS restrictions for web apps ✅ Monitor usage regularly ✅ Rotate keys on schedule ✅ Revoke compromised keys immediately ✅ Implement retry logic with backoff ✅ Log API key usage for auditing

Next Steps

• Integration Guide - Use keys in your app
• API Reference - Full authentication docs
• Best Practices - Production tips

---

Need help? Check our FAQ or contact support.