Skip to main content

API Keys Management

Learn how to issue, list, rotate, and revoke API keys for service accounts.

Overview​

API keys consist of two parts:

  • Access Key: Public identifier (e.g., sa_myorg_acc123_xyz789)
  • Secret Key: Private key used for HMAC signing (shown only once)

Issuing a New Key​

from pdaas import Client

client = Client(...)  # Authenticated as user

key = client.service_accounts.issue_key(
    service_account_id="sa-123",
    description="Production key",
    expires_at="2026-12-31T23:59:59Z"  # Optional
)

# ⚠️ IMPORTANT: Store these securely!
print(f"Access Key: {key['access_key']}")
print(f"Secret Key: {key['secret_key']}")  # Only shown once!
:class: warning
The secret key is displayed only once. Store it in a secure secret manager (AWS Secrets Manager, HashiCorp Vault, etc.) immediately!

Listing Keys​

keys = client.service_accounts.list_keys(
    service_account_id="sa-123"
)

for key in keys['results']:
    print(f"{key['id']}: {key['description']} - Expires: {key['expires_at']}")

Response:

{
  "total": 2,
  "page": 1,
  "results": [
    {
      "id": "key-abc",
      "access_key": "sa_myorg_acc123_abc",
      "description": "Production key",
      "service_account_id": "sa-123",
      "expires_at": "2026-12-31T23:59:59Z",
      "is_active": true,
      "created_at": "2025-09-30T10:00:00Z",
      "last_used_at": "2025-09-30T11:30:00Z"
    }
  ]
}

Rotating Keys​

Key rotation is a security best practice. Rotate keys every 90 days:

Step 1: Issue a new key

new_key = client.service_accounts.issue_key(
    service_account_id="sa-123",
    description="Production key (rotated 2025-09-30)"
)

Step 2: Deploy the new key to your services

Step 3: Verify the new key works

Step 4: Revoke the old key

client.service_accounts.revoke_key(
    service_account_id="sa-123",
    key_id="key-old"
)

Revoking Keys​

Immediately revoke a key if compromised:

client.service_accounts.revoke_key(
    service_account_id="sa-123",
    key_id="key-abc"
)
:class: warning
Revocation takes effect immediately. All requests using the revoked key will fail.

Key Expiration​

Set expiration dates to enforce key rotation:

# Expires in 90 days
from datetime import datetime, timedelta, UTC

expires_at = (datetime.now(UTC) + timedelta(days=90)).isoformat()

key = client.service_accounts.issue_key(
    service_account_id="sa-123",
    description="Q4 2025 key",
    expires_at=expires_at
)

Best Practices​

:class: tip
- ✅ Rotate keys every 90 days
- ✅ Set expiration dates on all keys
- ✅ Use one key per environment (dev, staging, prod)
- ✅ Store secrets in a secret manager (not environment variables in code)
- ✅ Revoke keys immediately when compromised
- ✅ Monitor key usage via audit logs
- ❌ Never commit keys to version control
- ❌ Never share keys between services
- ❌ Never store keys in plaintext

Monitoring Key Usage​

Track key usage in audit logs:

# Query audit logs for service account activity
logs = client.audit.query(
    actor_type="ServiceAccount",
    actor_id="sa-123",
    start_date="2025-09-01T00:00:00Z",
    end_date="2025-09-30T23:59:59Z"
)

for log in logs['results']:
    print(f"{log['timestamp']}: {log['action']} on {log['resource_type']}")

Next Steps​