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

Method	Endpoint	Description
GET	/api/api-keys	List all API keys
POST	/api/api-keys	Create a new API key
DELETE	/api/api-keys/{keyId}	Revoke an API key

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": "key_abc123",
      "name": "CI/CD Pipeline",
      "prefix": "whr_live_abc...",
      "scopes": ["read", "write"],
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-20T14:25:00Z",
      "expiresAt": "2024-04-15T10:30:00Z"
    }
  ]
}

Example

curl

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

JavaScript

const response = await fetch('https://api.hookbase.app/api/api-keys', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.hookbase.app/api/api-keys',
    headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Create API Key

Create a new API key for programmatic access.

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

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the key
scopes	string[]	No	Permissions: read, write (default: ["read", "write"])
expiresInDays	number	No	Days until expiration (default: never)

{
  "name": "GitHub Actions",
  "scopes": ["read", "write"],
  "expiresInDays": 90
}

Response

WARNING

The key value is only returned once. Store it securely!

{
  "apiKey": {
    "id": "key_xyz789",
    "name": "GitHub Actions",
    "prefix": "whr_live_xyz...",
    "scopes": ["read", "write"],
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-04-15T10:30:00Z"
  },
  "key": "whr_live_xyz789abc123def456..."
}

Example

curl

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"],
    "expiresInDays": 90
  }'

JavaScript

const response = await fetch('https://api.hookbase.app/api/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub Actions',
    scopes: ['read', 'write'],
    expiresInDays: 90
  })
});
const data = await response.json();

Python

import requests

response = requests.post(
    'https://api.hookbase.app/api/api-keys',
    headers={
        'Authorization': 'Bearer whr_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'GitHub Actions',
        'scopes': ['read', 'write'],
        'expiresInDays': 90
    }
)
data = response.json()

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

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

JavaScript

const response = await fetch('https://api.hookbase.app/api/api-keys/key_abc123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

Python

import requests

response = requests.delete(
    'https://api.hookbase.app/api/api-keys/key_abc123',
    headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Using API Keys

Include the API key in the Authorization header:

curl

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

JavaScript

const response = await fetch('https://api.hookbase.app/api/sources', {
  headers: {
    'Authorization': 'Bearer whr_live_xyz789abc123...'
  }
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.hookbase.app/api/sources',
    headers={'Authorization': 'Bearer whr_live_xyz789abc123...'}
)
data = response.json()

Or use the X-API-Key header:

curl

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

JavaScript

const response = await fetch('https://api.hookbase.app/api/sources', {
  headers: {
    'X-API-Key': 'whr_live_xyz789abc123...'
  }
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://api.hookbase.app/api/sources',
    headers={'X-API-Key': 'whr_live_xyz789abc123...'}
)
data = response.json()

Scopes

Scope	Description
read	View resources (sources, destinations, events, etc.)
write	Create, update, and delete resources

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: ${{ secrets.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_live_xyz789..."
hookbase sources list