API Keys

API keys provide a simple way to authenticate server-to-server requests. This guide covers key management, security best practices, and common patterns.

Overview

API keys are long-lived credentials designed for:

• Backend services and microservices
• CI/CD pipelines
• Automated scripts and cron jobs
• Server-side integrations

Not for Client-Side Use

Never expose API keys in client-side code (browsers, mobile apps). Use OAuth 2.0 or JWT tokens for client applications.

Key Types

Type	Prefix	Environment	Use Case
Live	ak_live_	Production	Production workloads
Test	ak_test_	Sandbox	Development and testing

Obtaining API Keys

Via Developer Portal

1. Log in to the Developer Portal
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Configure key settings (name, permissions, IP allowlist)
5. Copy and securely store the key

One-Time Display

The full API key is only shown once at creation. Store it immediately in a secure location.

Via API (Admin Only)

curl -X POST "https://platform.powerverse.com/admin/api-keys" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Asset Controls Backend",
    "permissions": ["read:assets", "write:schedules"],
    "ip_allowlist": ["10.0.0.0/8"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Using API Keys

Include the key in the X-API-Key header:

curl -X GET "https://platform.powerverse.com/inventory-service/sites" \
  -H "X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Language Examples

Python

import requests
import os

API_KEY = os.environ['POWERVERSE_API_KEY']

response = requests.get(
    "https://platform.powerverse.com/inventory-service/sites",
    headers={"X-API-Key": API_KEY}
)

Node.js

const apiKey = process.env.POWERVERSE_API_KEY;

const response = await fetch("https://platform.powerverse.com/inventory-service/sites", {
  headers: {
    "X-API-Key": apiKey
  }
});

Go

package main

import (
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("POWERVERSE_API_KEY")
    
    req, _ := http.NewRequest("GET", "https://platform.powerverse.com/inventory-service/sites", nil)
    req.Header.Set("X-API-Key", apiKey)
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Key Configuration

Permissions

Assign specific permissions to limit key access:

{
  "name": "Schedule Management Service",
  "permissions": [
    "read:schedules",
    "write:schedules",
    "read:assets"
  ]
}

IP Allowlisting

Restrict key usage to specific IP addresses or ranges:

{
  "name": "Production Backend",
  "ip_allowlist": [
    "203.0.113.0/24",
    "198.51.100.50"
  ]
}

Expiration

Set automatic expiration for enhanced security:

{
  "name": "Temporary Integration",
  "expires_at": "2024-06-30T23:59:59Z"
}

Managing API Keys

List Keys

curl -X GET "https://platform.powerverse.com/admin/api-keys" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Response:

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Asset Controls Backend",
      "prefix": "ak_live_xxxx",
      "permissions": ["read:assets", "write:schedules"],
      "created_at": "2024-01-15T10:00:00Z",
      "last_used_at": "2024-01-20T14:30:00Z",
      "expires_at": null
    }
  ]
}

Rotate Keys

To rotate a key safely:

# 1. Create new key
curl -X POST "https://platform.powerverse.com/admin/api-keys" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -d '{"name": "Asset Controls Backend (rotated)"}'

# 2. Update your applications with the new key

# 3. Verify the new key works

# 4. Revoke the old key
curl -X DELETE "https://platform.powerverse.com/admin/api-keys/key_old123" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Revoke Keys

Immediately disable a compromised key:

curl -X DELETE "https://platform.powerverse.com/admin/api-keys/key_abc123" \
  -H "Authorization: Bearer ADMIN_TOKEN"

Security Best Practices

Storage

✅ Do	❌ Don't
Use environment variables	Hardcode in source code
Use secret managers (Vault, AWS Secrets Manager)	Commit to version control
Encrypt at rest	Store in plain text files
Limit access to key storage	Share keys via email/chat

Environment Variables

# .env (never commit this file)
POWERVERSE_API_KEY=ak_live_xxxxxxxxxxxxxxxxxxxx

# .gitignore
.env
.env.*

Secret Managers

AWS Secrets Manager:

import boto3
import json

client = boto3.client('secretsmanager')
response = client.get_secret_value(SecretId='powerverse-api-key')
api_key = json.loads(response['SecretString'])['api_key']

HashiCorp Vault:

vault kv get -field=api_key secret/powerverse-api

Monitoring

Monitor API key usage for anomalies:

• Unusual request volumes
• Requests from unexpected IPs
• Access to resources outside normal scope
• Failed authentication attempts

Troubleshooting

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Causes:

• Typo in the key
• Key was revoked
• Using test key in production (or vice versa)

Expired API Key

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "This API key has expired",
    "details": {
      "expired_at": "2024-01-15T00:00:00Z"
    }
  }
}

IP Not Allowed

{
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Request from this IP address is not allowed",
    "details": {
      "client_ip": "203.0.113.50",
      "allowed_ips": ["10.0.0.0/8"]
    }
  }
}

Next Steps

• OAuth 2.0 - For third-party integrations
• Rate Limits - API key rate limiting
• Error Handling - Handling authentication errors