API Keys

API keys provide a way to authenticate with HookWatch without using JWT tokens. They're ideal for CLI tools, scripts, and server-to-server communication.

When to Use API Keys

Use API Keys for:

  • CLI tools and scripts
  • CI/CD pipelines
  • Server-to-server requests
  • Long-running processes

Use JWT Tokens for:

  • Browser applications
  • User-facing dashboards
  • Short-lived sessions
  • OAuth flows

Base URL

https://api.hookwatch.dev/v1/api-keys

The API Key Object

Json

Key Visibility

The full API key is only shown once when created. After that, only a masked version is returned.

List API Keys

Retrieve all API keys for the authenticated user.

GET /v1/api-keys

Create API Key

Create a new API key.

POST /v1/api-keys

Request Body

FieldTypeRequiredDescription
namestringYesA descriptive name for the key
expires_atstringNoOptional ISO 8601 expiry timestamp. Key never expires if omitted.

Response

Json

Store Securely

Copy and store the API key immediately. You won't be able to see it again.

Get API Key

Retrieve details about a specific API key (key is masked).

GET /v1/api-keys/:id

Delete API Key

Revoke an API key. This action is immediate and irreversible.

DELETE /v1/api-keys/:id

Using API Keys

API keys can be used with the CLI or REST API:

Terminal

Best Practices

  • Create separate keys for different environments (development, staging, production)
  • Use descriptive names to identify where each key is used
  • Rotate keys periodically and after any suspected compromise
  • Never commit API keys to version control - use environment variables
  • Delete unused keys to minimize exposure

Related