Question 1

How do I create an API key?

Accepted Answer

You can create an API key by clicking the "Create Key" button on the home page. No authentication is required for your first key. Simply provide a name and select the permissions you need. Your key will be generated automatically with a unique client UUID.

Question 2

Do I need to sign up or create an account?

Accepted Answer

No account is required. PlatPhorm Keys uses a self-service provisioning model. When you create your first key, a unique client UUID is automatically generated and associated with your keys. Store this UUID securely as it identifies your tenant.

Question 3

What scopes/permissions are available?

Accepted Answer

Four scopes are available: Read (view resources), Write (create/update resources), Delete (remove resources), and Admin (full access). We recommend starting with Read-only access and adding more permissions as needed.

Question 4

How are my API keys stored?

Accepted Answer

All API keys are encrypted using AES-256-GCM before storage in DynamoDB. Each key has a unique initialization vector (IV) and authentication tag. The plaintext key is only shown once at creation time and cannot be retrieved afterward.

Question 5

What is the key prefix shown in the dashboard?

Accepted Answer

The key prefix (e.g., "pk_live_") is the first 8 characters of your key. It allows you to identify keys without exposing the full value. Production keys start with "pk_live_" and test keys with "pk_test_".

Question 6

Can I recover a lost API key?

Accepted Answer

No. For security reasons, the plaintext key is only displayed once at creation. If you lose your key, you must create a new one or rotate an existing key. This ensures that even if our database is compromised, your keys remain secure.

Question 7

What is key rotation and when should I use it?

Accepted Answer

Key rotation generates a new key value while keeping the same key ID and settings. Use it when you suspect a key may have been compromised, for regular security hygiene (e.g., every 90 days), or when team members with access leave.

Question 8

What are the rate limits?

Accepted Answer

Key provisioning is limited to 5 keys per hour per client/IP combination. Authenticated API operations are limited to 100 requests per minute per tenant. These limits help prevent abuse while allowing normal usage.

Question 9

How do I authenticate API requests?

Accepted Answer

Include your API key in requests using either the Authorization header (Bearer token) or the X-API-Key header. Example: "Authorization: Bearer pk_live_xxxx" or "X-API-Key: pk_live_xxxx".

Question 10

What is the client UUID and fingerprint?

Accepted Answer

When you provision a key, we automatically generate a client UUID (unique identifier for your tenant) and a fingerprint (derived from your browser/device). These help with tracking, security, and rate limiting.

Question 11

What is OpenTelemetry integration?

Accepted Answer

Every API request generates trace IDs compatible with W3C Trace Context. This enables distributed tracing across your applications. Trace IDs are returned in response headers (X-Trace-Id) and stored with audit logs.

Question 12

How can I monitor my API key usage?

Accepted Answer

Each key tracks its last used timestamp and total usage count. The dashboard shows this information, and you can also query the telemetry endpoint at /api/v1/telemetry for detailed metrics and recent spans.

Question 13

Are API key operations logged?

Accepted Answer

Yes, all key operations (create, update, rotate, revoke, delete, validate) are logged with timestamps, IP addresses, user agents, and trace IDs. This audit trail helps with security investigations and compliance.

Question 14

How should I store my API keys?

Accepted Answer

Store API keys in environment variables or a secure secrets manager. Never commit keys to version control, embed them in client-side code, or share them in plain text. Use different keys for development and production.

Question 15

What should I do if my key is compromised?

Accepted Answer

Immediately revoke the compromised key from the dashboard. Then create a new key or rotate an existing one. Review your audit logs to check for unauthorized usage. Update your applications with the new key.

Question 16

Should I use one key or multiple keys?

Accepted Answer

Use separate keys for different applications, environments (dev/staging/prod), and team members. This allows granular access control and easier revocation if a specific key is compromised.

Frequently Asked Questions

Getting Started

Security

Usage & Limits

Observability

Best Practices

Still have questions?