API Keys Management

Enterprise-grade API key management for Pocketbook, including creation, rotation, permissions, and security best practices.

Overview

API keys provide programmatic access to Pocketbook services. Enterprise accounts benefit from:

Multiple API keys: Create separate keys for different services
Fine-grained permissions: Control access at the endpoint level
Usage tracking: Monitor API usage per key
Rate limits: Custom rate limits per key
Key rotation: Automated and manual key rotation
Team management: Share keys with team members
Audit logging: Track all API key usage

API Key Types

Production Keys

Used for live production environments:

Prefix: pk_live_
Access to production data
Strict rate limits
Full audit logging

Test Keys

Used for development and testing:

Prefix: pk_test_
Access to test/sandbox data
Relaxed rate limits
Separate from production

Restricted Keys

Limited scope keys for specific use cases:

Prefix: pk_restricted_
Custom permission sets
Limited endpoints
Time-bound access

Creating API Keys

Via Dashboard

Navigate to Settings > API Keys
Click Create New API Key
Configure key settings:
- Name: Descriptive name (e.g., "Production Backend")
- Type: Production, Test, or Restricted
- Permissions: Select allowed operations
- Rate Limit: Set custom rate limit
- Expiration: Optional expiration date
Click Create Key
Important: Copy the key immediately (shown only once)

Via API

bash

curl -X POST "https://api.pocketbook.studio/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "type": "production",
    "permissions": ["transactions.read", "transactions.create"],
    "rateLimit": 1000,
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

Response:

json

{
  "id": "apikey_abc123",
  "key": "pk_live_xyz789...",
  "name": "Production Backend",
  "type": "production",
  "permissions": ["transactions.read", "transactions.create"],
  "rateLimit": 1000,
  "expiresAt": "2025-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

Permission Scopes

Resource-Level Permissions

Grant access to specific resource types:

json

{
  "permissions": [
    "transactions.read",
    "transactions.create",
    "transactions.update",
    "users.read",
    "reports.read"
  ]
}

Available Scopes

Transactions:

transactions.read - View transactions
transactions.create - Create new transactions
transactions.update - Update existing transactions
transactions.delete - Delete transactions
transactions.* - All transaction permissions

Users:

users.read - View user information
users.create - Create new users
users.update - Update user information
users.delete - Delete users
users.* - All user permissions

Reports:

reports.read - View reports
reports.create - Generate reports
reports.export - Export reports
reports.* - All report permissions

Billing:

billing.read - View billing information
billing.invoices - Manage invoices
billing.payments - Process payments
billing.* - All billing permissions

Admin:

admin.* - Full administrative access (use with caution)

Custom Permission Sets

Create reusable permission sets:

typescript

// src/config/permission-sets.ts
export const PERMISSION_SETS = {
  readonly: [
    'transactions.read',
    'users.read',
    'reports.read',
  ],
  backend_service: [
    'transactions.read',
    'transactions.create',
    'users.read',
    'users.update',
  ],
  reporting_service: [
    'reports.read',
    'reports.create',
    'reports.export',
    'transactions.read',
  ],
  admin: [
    'admin.*',
  ],
};

Using API Keys

Authentication Header

bash

curl -X GET "https://api.pocketbook.studio/api/v1/transactions" \
  -H "Authorization: Bearer pk_live_your_key_here"

Query Parameter (Not Recommended)

bash

curl -X GET "https://api.pocketbook.studio/api/v1/transactions?api_key=pk_live_your_key_here"

Note: Using query parameters exposes keys in logs. Always use headers in production.

SDK Configuration

typescript

// Node.js
import { Pocketbook } from '@pocketbook/sdk';

const client = new Pocketbook({
  apiKey: process.env.POCKETBOOK_API_KEY,
  environment: 'production',
});

// Make authenticated requests
const transactions = await client.transactions.list();

python

# Python
from pocketbook import Pocketbook

client = Pocketbook(
    api_key=os.environ['POCKETBOOK_API_KEY'],
    environment='production'
)

transactions = client.transactions.list()

Managing API Keys

List All Keys

http

GET /api/v1/api-keys

Response:

json

{
  "apiKeys": [
    {
      "id": "apikey_abc123",
      "name": "Production Backend",
      "type": "production",
      "permissions": ["transactions.*"],
      "lastUsedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "expiresAt": null,
      "status": "active"
    }
  ]
}

Get Key Details

http

GET /api/v1/api-keys/{key_id}

Update Key

http

PATCH /api/v1/api-keys/{key_id}
Content-Type: application/json

{
  "name": "Updated Name",
  "permissions": ["transactions.read", "users.read"],
  "rateLimit": 2000
}

Revoke Key

http

DELETE /api/v1/api-keys/{key_id}

Important: Revoked keys cannot be restored. Update your applications before revoking.

Key Rotation

Manual Rotation

Create new API key with same permissions
Update applications with new key
Test new key in staging
Deploy to production
Monitor for errors
Revoke old key after grace period (7-30 days)

Automated Rotation

typescript

// scripts/rotate-api-key.ts
import { Pocketbook } from '@pocketbook/sdk';

async function rotateApiKey(oldKeyId: string): Promise<string> {
  const client = new Pocketbook({ apiKey: process.env.ADMIN_KEY });

  // Get old key details
  const oldKey = await client.apiKeys.retrieve(oldKeyId);

  // Create new key with same permissions
  const newKey = await client.apiKeys.create({
    name: `${oldKey.name} (Rotated)`,
    type: oldKey.type,
    permissions: oldKey.permissions,
    rateLimit: oldKey.rateLimit,
  });

  console.log('New API key created:', newKey.id);
  console.log('API Key:', newKey.key); // Store securely!

  // Schedule old key revocation
  setTimeout(async () => {
    await client.apiKeys.delete(oldKeyId);
    console.log('Old API key revoked:', oldKeyId);
  }, 7 * 24 * 60 * 60 * 1000); // 7 days

  return newKey.key;
}

See Key Rotation Guide for detailed rotation strategies.

Rate Limits

Default Limits

Key Type	Requests/Minute	Requests/Hour	Burst
Production	1,000	50,000	100
Test	100	5,000	20
Restricted	Custom	Custom	Custom

Custom Rate Limits

Enterprise accounts can request custom rate limits:

bash

curl -X PATCH "https://api.pocketbook.studio/api/v1/api-keys/{key_id}" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rateLimit": 5000
  }'

Rate Limit Headers

API responses include rate limit information:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642262400

Handling Rate Limits

typescript

async function makeApiRequest(url: string): Promise<any> {
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
    },
  });

  if (response.status === 429) {
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
    const waitTime = resetTime - Math.floor(Date.now() / 1000);

    console.log(`Rate limited. Waiting ${waitTime} seconds...`);
    await new Promise(resolve => setTimeout(resolve, waitTime * 1000));

    // Retry request
    return makeApiRequest(url);
  }

  return response.json();
}

Usage Tracking

View Usage Statistics

http

GET /api/v1/api-keys/{key_id}/usage?period=7d

Response:

json

{
  "keyId": "apikey_abc123",
  "period": "7d",
  "totalRequests": 45678,
  "successfulRequests": 45234,
  "failedRequests": 444,
  "averageLatency": 125,
  "endpoints": [
    {
      "path": "/api/v1/transactions",
      "method": "GET",
      "requests": 30000,
      "avgLatency": 95
    },
    {
      "path": "/api/v1/users",
      "method": "GET",
      "requests": 15678,
      "avgLatency": 150
    }
  ]
}

Usage Alerts

Configure alerts for unusual activity:

typescript

// src/monitoring/api-key-alerts.ts
export function setupUsageAlerts(keyId: string) {
  // Alert on high error rate
  if (errorRate > 0.05) { // 5%
    alertTeam('High error rate for API key', { keyId, errorRate });
  }

  // Alert on unusual spike
  if (requestsPerMinute > rateLimit * 0.9) {
    alertTeam('Approaching rate limit', { keyId, requestsPerMinute });
  }

  // Alert on unauthorized access attempts
  if (unauthorizedAttempts > 10) {
    alertTeam('Unauthorized access attempts detected', { keyId });
  }
}

Security Best Practices

1. Store Keys Securely

Never:

Commit keys to version control
Share keys via email or chat
Hardcode keys in source code
Log full API keys

Always:

Use environment variables
Store in secrets manager (AWS Secrets Manager, Vault)
Rotate keys regularly
Use restricted keys when possible

typescript

// ✅ Good
const apiKey = process.env.POCKETBOOK_API_KEY;

// ❌ Bad
const apiKey = 'pk_live_abc123...'; // Hardcoded

2. Use Minimum Required Permissions

Grant only necessary permissions:

typescript

// ✅ Good - Specific permissions
const readOnlyKey = await client.apiKeys.create({
  permissions: ['transactions.read'],
});

// ❌ Bad - Overly permissive
const adminKey = await client.apiKeys.create({
  permissions: ['admin.*'],
});

3. Set Expiration Dates

Create time-limited keys for temporary access:

typescript

const temporaryKey = await client.apiKeys.create({
  name: 'Contractor Access',
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
});

4. Monitor Usage

Regularly review API key usage:

Check for unused keys
Monitor unusual activity
Review permission scopes
Audit access logs

5. Implement Key Rotation

Rotate keys every 90 days or when:

Team member leaves
Key may be compromised
Changing environments
Upgrading security posture

Team Collaboration

http

POST /api/v1/api-keys/{key_id}/share
Content-Type: application/json

{
  "userIds": ["user_123", "user_456"],
  "permissions": ["read", "rotate"]
}

Access Levels

Owner: Full control, can delete key
Admin: Can rotate and manage permissions
Editor: Can view and use key
Viewer: Can only view key details (not the actual key)

Compliance & Audit

Audit Logs

All API key operations are logged:

http

GET /api/v1/api-keys/{key_id}/audit-logs

Response:

json

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "action": "key.created",
      "userId": "user_123",
      "ipAddress": "192.168.1.1"
    },
    {
      "timestamp": "2024-01-15T11:00:00Z",
      "action": "key.used",
      "endpoint": "/api/v1/transactions",
      "statusCode": 200
    }
  ]
}

Compliance Reports

Generate compliance reports for audits:

typescript

const report = await client.apiKeys.generateComplianceReport({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  includeUsage: true,
  includeAuditLogs: true,
});

Troubleshooting

Common Issues

401 Unauthorized

Check API key is correct
Verify key hasn't expired
Ensure key hasn't been revoked

403 Forbidden

Check key has required permissions
Verify IP whitelist (if configured)

429 Too Many Requests

Implement exponential backoff
Request rate limit increase
Use multiple keys for load distribution

Next Steps

Authentication Guide - Authentication methods
API Reference - Complete API documentation
Security Guide - Security best practices
Key Rotation - Automated key rotation

Overview ​

API Key Types ​

Production Keys ​

Test Keys ​

Restricted Keys ​

Creating API Keys ​

Via Dashboard ​

Via API ​

Permission Scopes ​

Resource-Level Permissions ​

Available Scopes ​

Custom Permission Sets ​

Using API Keys ​

Authentication Header ​

Query Parameter (Not Recommended) ​

SDK Configuration ​

Managing API Keys ​

List All Keys ​

Get Key Details ​

Update Key ​

Revoke Key ​

Key Rotation ​

Manual Rotation ​

Automated Rotation ​

Rate Limits ​

Default Limits ​

Custom Rate Limits ​

Rate Limit Headers ​

Handling Rate Limits ​

Usage Tracking ​

View Usage Statistics ​

Usage Alerts ​

Security Best Practices ​

1. Store Keys Securely ​

2. Use Minimum Required Permissions ​

3. Set Expiration Dates ​

4. Monitor Usage ​

5. Implement Key Rotation ​

Team Collaboration ​

Share Keys with Team ​

Access Levels ​

Compliance & Audit ​

Audit Logs ​

Compliance Reports ​

Troubleshooting ​

Common Issues ​

Next Steps ​

Resources ​

Overview

API Key Types

Production Keys

Test Keys

Restricted Keys

Creating API Keys

Via Dashboard

Via API

Permission Scopes

Resource-Level Permissions

Available Scopes

Custom Permission Sets

Using API Keys

Authentication Header

Query Parameter (Not Recommended)

SDK Configuration

Managing API Keys

List All Keys

Get Key Details

Update Key

Revoke Key

Key Rotation

Manual Rotation

Automated Rotation

Rate Limits

Default Limits

Custom Rate Limits

Rate Limit Headers

Handling Rate Limits

Usage Tracking

View Usage Statistics

Usage Alerts

Security Best Practices

1. Store Keys Securely

2. Use Minimum Required Permissions

3. Set Expiration Dates

4. Monitor Usage

5. Implement Key Rotation

Team Collaboration

Share Keys with Team

Access Levels

Compliance & Audit

Audit Logs

Compliance Reports

Troubleshooting

Common Issues

Next Steps

Resources