Manage API Keys

CRUD operations for API keys used in rate limiting on GenLayer Studio deployments.

Setup

Before any operation, determine the target environment:

1. Ask the user which environment they are targeting:
   • Local dev: BASE_URL=http://localhost:4000/api, no admin_key needed
   • Hosted (dev/stg/prd): BASE_URL=https://<domain>/api, requires admin_key
2. For hosted deployments, ask the user for the ADMIN_API_KEY (stored in k8s secrets as ADMIN_API_KEY).

Operations

Ask the user which operation to perform: Create, List, Deactivate, or Reactivate.

List API Keys

Note: This endpoint may not exist yet. If admin_listApiKeys is not available, query the database directly using the studio-db skill, or inform the user it needs to be implemented.

# List all keys
curl -s -X POST "$BASE_URL" -H "Content-Type: application/json" --data-binary @- <<'EOF' | python3 -m json.tool
{"jsonrpc":"2.0","method":"admin_listApiKeys","params":{"admin_key":"<ADMIN_KEY>"},"id":1}
EOF

# Filter by tier
curl -s -X POST "$BASE_URL" -H "Content-Type: application/json" --data-binary @- <<'EOF' | python3 -m json.tool
{"jsonrpc":"2.0","method":"admin_listApiKeys","params":{"tier_name":"free","admin_key":"<ADMIN_KEY>"},"id":1}
EOF

# Filter by active status
curl -s -X POST "$BASE_URL" -H "Content-Type: application/json" --data-binary @- <<'EOF' | python3 -m json.tool
{"jsonrpc":"2.0","method":"admin_listApiKeys","params":{"is_active":false,"admin_key":"<ADMIN_KEY>"},"id":1}
EOF

Create API Key

Ask the user for: tier_name (suggest listing tiers first with /manage-tiers) and optional description.

curl -s -X POST "$BASE_URL" -H "Content-Type: application/json" --data-binary @- <<'EOF' | python3 -m json.tool
{"jsonrpc":"2.0","method":"admin_createApiKey","params":{"tier_name":"<TIER_NAME>","description":"<DESCRIPTION>","admin_key":"<ADMIN_KEY>"},"id":1}
EOF

IMPORTANT: The full API key (e.g., glk_abcdef1234...) is only returned once at creation time. Remind the user to store it securely. Only the key_prefix (first 8 chars) is stored for identification.

Response includes:

• api_key: Full key (store this!)
• key_prefix: First 8 characters (e.g., glk_ab12)
• tier: Tier name
• description: Optional description

Deactivate API Key

Ask the user for the key_prefix (8 characters, e.g., glk_ab12). If they don't know it, list keys first.

curl -s -X POST "$BASE_URL" -H "Content-Type: application/json" --data-binary @- <<'EOF' | python3 -m json.tool
{"jsonrpc":"2.0","method":"admin_deactivateApiKey","params":{"key_prefix":"<KEY_PREFIX>","admin_key":"<ADMIN_KEY>"},"id":1}
EOF

Deactivation takes effect immediately (Redis cache is invalidated).

Reactivate API Key

Note: This endpoint may not exist yet. If admin_reactivateApiKey is not available, inform the user it needs to be implemented.

curl -s -X POST "$BASE_URL" -H "Content-Type: application/json" --data-binary @- <<'EOF' | python3 -m json.tool
{"jsonrpc":"2.0","method":"admin_reactivateApiKey","params":{"key_prefix":"<KEY_PREFIX>","admin_key":"<ADMIN_KEY>"},"id":1}
EOF

API Key Usage

Clients send the API key via the X-API-Key HTTP header:

curl -X POST "$BASE_URL" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: glk_<full_key>" \
  -d '{"jsonrpc":"2.0","method":"<method>","params":{...},"id":1}'

• Requests without X-API-Key are subject to anonymous rate limits (default: 10/min, 100/hr, 1000/day).
• Invalid or deactivated keys return -32029 "Invalid API key".
• When the rate limit is exceeded, the response is HTTP 429 with a JSON-RPC error including window, limit, current, and retry_after_seconds.

Common Errors

Key Format

• Full key: glk_ + 64 hex characters (68 chars total)
• Key prefix: first 8 characters (e.g., glk_ab12)
• Storage: only the SHA-256 hash is stored in the database; the full key cannot be recovered

Important Notes

• Always use --data-binary @- with heredoc (<<'EOF') to avoid shell expansion issues with special characters in the admin key.
• When rate limiting is disabled (RATE_LIMIT_ENABLED=false), keys can still be created and managed, but rate limits are not enforced and invalid keys are not rejected.
• Cache invalidation happens automatically on deactivate/reactivate (5-minute TTL otherwise).

Reference

• Models: backend/database_handler/models.py (ApiKey class)
• Endpoints: backend/protocol_rpc/endpoints.py (admin_create_api_key, admin_deactivate_api_key)
• Rate limiter: backend/protocol_rpc/rate_limiter.py
• Middleware: backend/protocol_rpc/rate_limit_middleware.py