Overview

Manage multiple API keys for different applications, environments, or team members. Each key can be individually created, monitored, and revoked without affecting other integrations.

How It Works

1. Create API keys from the Enterprise dashboard
2. Each key has:
– A descriptive name
– Creation date
– Last used timestamp
– Individual revocation capability
3. Keys are used to authenticate REST API requests
4. All API key actions are logged in the audit trail
5. Revoking a key immediately blocks all requests using it

Tier Availability

| Tier | Available |
|——|———–|
| Enterprise | Yes |

Related Features

– Public REST API: API that keys authenticate against
– Webhook Management: Complementary integration method
– Audit Trail: API key usage is tracked

Mini-Tutorial

Step 1: Create Your First API Key

Go to Enterprise > API Keys and click “Generate New Key.”

Step 2: Name It Descriptively

Examples: “Production Server”, “CI/CD Pipeline”, “Mobile App”, “Third-Party Service”.

Step 3: Set Expiration (Optional)

Choose when the key expires (optional, can set to never expire). Short-lived keys are more secure.

Step 4: Generate

Click “Generate Key.” You’ll see the full key only once. Copy it immediately.

Step 5: Store Safely

Store the key in a secure location:
– Environment variables (recommended)
– Secrets manager (AWS Secrets Manager, HashiCorp Vault)
– Never commit to version control

Step 6: Use in Requests

Add the key to your API requests via X-API-Key header and start validating via API.

Step 7: Manage Multiple Keys

Create separate keys for different environments (dev, staging, production) or services.

Step 8: Revoke When Needed

If a key is compromised, immediately delete it from the dashboard. All requests using it will fail.

Technical Details

Create API Key

POST /api/v1/api-keys
X-API-Key: sk_live_existing_key...
Content-Type: application/json

{
  "name": "Production API",
  "expires_in_days": 365
}

Response (shown only once):

{
  "id": "key_abc123",
  "name": "Production API",
  "key": "sk_live_1a2b3c4d5e6f7g8h9i0j...",
  "created_at": "2025-03-22T14:30:00Z",
  "expires_at": "2026-03-22T14:30:00Z",
  "status": "active"
}

List API Keys

GET /api/v1/api-keys
X-API-Key: sk_live_existing_key...

Response:

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production API",
      "created_at": "2025-03-22T14:30:00Z",
      "expires_at": "2026-03-22T14:30:00Z",
      "last_used_at": "2025-03-22T14:45:00Z",
      "status": "active"
    },
    {
      "id": "key_def456",
      "name": "CI/CD Pipeline",
      "created_at": "2025-03-01T10:00:00Z",
      "expires_at": "2025-04-01T10:00:00Z",
      "last_used_at": null,
      "status": "active"
    }
  ]
}

Revoke/Delete API Key

DELETE /api/v1/api-keys/key_abc123
X-API-Key: sk_live_existing_key...

All requests using sk_live_1a2b3c4d... will immediately fail with 401 Unauthorized.

Using API Key in Requests

Every request requires the key:

GET /api/v1/projects
X-API-Key: sk_live_1a2b3c4d5e6f7g8h9i0j...

Or (alternative, less common):

GET /api/v1/projects?api_key=sk_live_1a2b3c4d...

Note: Header method is preferred for security; URL parameters can leak in logs.

Key Rotation Best Practices

1. Create a new key
2. Update application to use new key
3. Test thoroughly
4. Delete old key after confirming new one works
5. Do this before expiration to avoid service interruption

References

– API Key Security Best Practices
– NIST Digital Identity Guidelines
– Secrets Management (12 Factor App)
– ValidGraph API Key Documentation