API Keys

API keys provide programmatic access to the Hookbase API without requiring user authentication. They are ideal for CI/CD pipelines, server-to-server integrations, and automated workflows.

Overview

• API keys are scoped to a specific organization
• Keys can have read-only or read-write permissions
• Keys can be set to expire after a specified time
• The actual key value is only shown once upon creation

Endpoints

List API Keys

Retrieve all API keys for the organization. Key values are masked for security.

GET /api/api-keys
Authorization: Bearer {token}

Response

{
  "apiKeys": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "CI/CD Pipeline",
      "prefix": "whr_4f3c2a1b",
      "scopes": ["read", "write"],
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-20T14:25:00Z",
      "expiresAt": "2024-04-15T10:30:00Z"
    }
  ]
}

Example

curl https://api.hookbase.app/api/api-keys \
  -H "Authorization: Bearer whr_your_api_key"

Create API Key

Create a new API key for programmatic access.

POST /api/api-keys
Authorization: Bearer {token}
Content-Type: application/json

Request Body

{
  "name": "GitHub Actions",
  "scopes": ["read", "write"],
  "expiresIn": 7776000
}

Response

{
  "apiKey": {
    "id": "55555555-5555-4555-8555-555555550001",
    "name": "GitHub Actions",
    "prefix": "whr_4f3c2a1b",
    "scopes": ["read", "write"],
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-04-15T10:30:00Z"
  },
  "key": "whr_4f3c2a1b9d8e7f6a5b4c3d2e1f0a9b8c"
}

Example

curl -X POST https://api.hookbase.app/api/api-keys \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions",
    "scopes": ["read", "write"],
    "expiresIn": 7776000
  }'

Revoke API Key

Permanently revoke an API key. This action cannot be undone.

DELETE /api/api-keys/{keyId}
Authorization: Bearer {token}

Response

{
  "success": true
}

Example

curl -X DELETE https://api.hookbase.app/api/api-keys/55555555-5555-4555-8555-555555555555 \
  -H "Authorization: Bearer whr_your_api_key"

Using API Keys

Include the API key in the Authorization header:

curl https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_4f3c2a1b9d8e7f6a5b4c3d2e1f0a9b8c"

Or use the X-API-Key header:

curl https://api.hookbase.app/api/sources \
  -H "X-API-Key: whr_4f3c2a1b9d8e7f6a5b4c3d2e1f0a9b8c"

Scopes

A key with only read scope can:

• List and view sources, destinations, routes
• View events and deliveries
• View analytics

A key with write scope can additionally:

• Create, update, delete sources
• Create, update, delete destinations
• Create, update, delete routes
• Replay deliveries
• Manage tunnels

Best Practices

1. Use descriptive names: Name keys based on their purpose (e.g., "GitHub Actions CI", "Production Backup Script")

2. Set expiration dates: For security, set expiration dates on keys, especially for temporary access

3. Minimize scopes: Only grant the permissions needed. Use read-only keys when write access isn't required

4. Rotate regularly: Periodically rotate keys, especially if they may have been exposed

5. Store securely:

   • Never commit API keys to version control
   • Use environment variables or secrets managers
   • The key is only shown once—store it immediately

6. Monitor usage: Check lastUsedAt to identify unused keys that can be revoked

Environment Variables

For CI/CD environments, set the API key as an environment variable:

# GitHub Actions
env:
  HOOKBASE_API_KEY: $
 
# GitLab CI
variables:
  HOOKBASE_API_KEY: $HOOKBASE_API_KEY
 
# CircleCI
environment:
  HOOKBASE_API_KEY: ${HOOKBASE_API_KEY}

Then use with the CLI:

export HOOKBASE_API_KEY="whr_4f3c2a1b9d8e7f6a5b4c3d2e1f0a9b8c"
hookbase sources list