API Key Management

Manage API keys for authenticating with the Email API. API keys are scoped to your account and can be created with specific permissions.

List API Keys

Retrieve all active API keys for your account.

Endpoint

GET /api/email/api-keys

Authentication

Required: Bearer token in Authorization header

Authorization: Bearer YOUR_API_KEY

Response (200 OK)

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "key_1234567890",
        "name": "Production API Key",
        "prefix": "pk_live_...",
        "permissions": ["send", "read"],
        "createdAt": "2024-01-15T10:30:00Z",
        "lastUsedAt": "2024-01-20T14:22:00Z",
        "expiresAt": null
      },
      {
        "id": "key_0987654321",
        "name": "Development API Key",
        "prefix": "pk_test_...",
        "permissions": ["send", "read", "webhooks"],
        "createdAt": "2024-01-10T08:00:00Z",
        "lastUsedAt": "2024-01-19T16:45:00Z",
        "expiresAt": "2024-12-31T23:59:59Z"
      }
    ]
  },
  "message": "API keys retrieved successfully"
}

Create API Key

Generate a new API key for your account.

Endpoint

POST /api/email/api-keys

Authentication

Required: Bearer token in Authorization header

Request Body

Field	Type	Required	Description
`name`	string	Yes	Descriptive name for the API key
`permissions`	array	No	Array of permissions (default: `["send", "read"]`
`expiresIn`	number	No	Expiration time in days (null for no expiry)

Permission Options

Permission	Description
`send`	Send emails
`read`	Read email history and status
`webhooks`	Manage webhook configurations
`admin`	Full access including API key management

Request Example

curl -X POST https://api.yourdomain.com/api/email/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "permissions": ["send", "read"],
    "expiresIn": 365
  }'

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "key_new123456789",
    "name": "Production API Key",
    "key": "pk_live_abc123xyz789_full_key_here",
    "prefix": "pk_live_...",
    "permissions": ["send", "read"],
    "createdAt": "2024-01-20T10:00:00Z",
    "expiresAt": "2025-01-20T10:00:00Z"
  },
  "message": "API key created successfully"
}

:::warning The full API key is only returned once upon creation. Store it securely as it cannot be retrieved again. :::

Revoke API Key

Revoke an existing API key to immediately invalidate it.

Endpoint

DELETE /api/email/api-keys/:id

Authentication

Required: Bearer token in Authorization header

Path Parameters

Parameter	Description
`id`	The API key ID (e.g., `key_1234567890`)

Request Example

curl -X DELETE https://api.yourdomain.com/api/email/api-keys/key_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "key_1234567890",
    "revokedAt": "2024-01-20T15:30:00Z"
  },
  "message": "API key revoked successfully"
}

Update API Key

Update the name or permissions of an existing API key.

Endpoint

PATCH /api/email/api-keys/:id

Authentication

Required: Bearer token in Authorization header

Request Body

Field	Type	Required	Description
`name`	string	No	New name for the API key
`permissions`	array	No	Updated permissions array

Request Example

curl -X PATCH https://api.yourdomain.com/api/email/api-keys/key_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Production Key",
    "permissions": ["send", "read", "webhooks"]
  }'

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "key_1234567890",
    "name": "Updated Production Key",
    "permissions": ["send", "read", "webhooks"],
    "updatedAt": "2024-01-20T16:00:00Z"
  },
  "message": "API key updated successfully"
}

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to manage API keys"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "API key not found"
  }
}

Best Practices

Use separate keys for different environments (development, staging, production)
Set expiration dates for enhanced security
Rotate keys regularly (every 90 days recommended)
Use minimal permissions - only grant what's needed
Revoke unused keys to reduce attack surface
Never commit API keys to version control

Rate Limits

API key management endpoints have stricter rate limits:

Create: 10 requests/minute
List/Update/Revoke: 60 requests/minute

API Key Management

On this page