Authentication

Hook Mesh uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure.

API Keys

Authentication to the API is performed via Bearer token authentication. All API requests must include your API key in the Authorization header.

Key Formats

sk_live_...Production keys

sk_test_...Test mode keys

Getting Your API Key

Navigate to Settings → API Keys in the dashboard
Click "Create API Key"
Copy the key immediately (it won't be shown again)
Store it securely in your environment variables

Keep your API keys secure! Never commit them to version control, expose them in client-side code, or share them publicly.

Making Authenticated Requests

Include your API key in the Authorization header as a Bearer token:

GET /v1/applications HTTP/1.1
Host: api.hookmesh.com
Authorization: Bearer sk_live_abc123...
Content-Type: application/json

cURL Example

curl https://api.hookmesh.com/v1/applications \
  -H "Authorization: Bearer sk_live_abc123..."
  -H "Content-Type: application/json"

JavaScript Example

const response = await fetch('https://api.hookmesh.com/v1/applications', {
  headers: {
    'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Python Example

import requests
import os

headers = {
    'Authorization': f'Bearer {os.environ.get("HOOKMESH_API_KEY")}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.hookmesh.com/v1/applications', headers=headers)
data = response.json()

Error Responses

401 Unauthorized

Returned when the API key is missing or invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

Returned when the API key doesn't have access to the requested resource:

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have access to this resource"
  }
}

Security Best Practices

✅ Do

• Store API keys in environment variables
• Use secret management services (AWS Secrets Manager, Vault)
• Rotate keys every 90 days
• Use test keys for development and staging
• Monitor API key usage in dashboard

❌ Don't

• Commit keys to version control
• Share keys between environments
• Expose keys in client-side code
• Use production keys in test environments
• Share keys with third parties

Managing API Keys

Listing Keys

GET /v1/api-keys

Returns a list of your API keys (keys themselves are not shown, only metadata):

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "prefix": "sk_live_abc",
      "created_at": "2026-01-15T10:00:00Z",
      "last_used_at": "2026-01-20T15:25:00Z"
    }
  ]
}

Creating Keys

POST /v1/api-keys

{
  "name": "Production Key",
  "scopes": ["applications:read", "webhooks:write"]
}

{
  "id": "key_abc123",
  "name": "Production Key",
  "key": "sk_live_abc123...",
  "created_at": "2026-01-20T15:30:00Z"
}

Save the key immediately! The full key is only shown once during creation. Store it securely.

Revoking Keys

DELETE /v1/api-keys/{key_id}

Immediately invalidates the key. Any requests using this key will receive a 401 error.

Rate Limiting

API requests are rate limited per organization:

Endpoint	Limit
Webhook job creation	`100/sec`
Endpoint testing	`10/min per endpoint`
Portal URL generation	`100/min`
API key creation	`10/hour`

Rate limit information is included in response headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1737380460

429 Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}