Authentication

HookWatch supports two authentication methods: JWT tokens for the dashboard and REST API, and API keys for the CLI and server-to-server communication.

Overview

HookWatch supports two authentication methods:

JWT Tokens

Short-lived access tokens for the dashboard and REST API. Uses a two-token system with access (15 min) and refresh (7 day) tokens.

API Keys

Long-lived keys for the CLI, scripts, and CI/CD. Passed via X-API-Key header or gRPC metadata.

Register

Create a new user account.

POST /v1/auth/register

Request Body

Json

Response

Json

Login

Authenticate with email and password to receive tokens.

POST /v1/auth/login

Request Body

Json

Response format is the same as the register endpoint.

Using Access Tokens

Include the access token in the Authorization header for all authenticated requests.

curl

Refresh Token

When your access token expires, use the refresh token to obtain a new one without re-authenticating.

POST /v1/auth/refresh

Request Body

Json

Response

Json

Get Current User

Retrieve information about the authenticated user.

GET /v1/auth/me

Response

Json

Change Password

Update the authenticated user's password.

POST /v1/auth/change-password

Request Body

FieldTypeRequiredDescription
current_passwordstringYesCurrent password
new_passwordstringYesNew password (min 8 characters)

API Key Authentication

For the CLI and server-to-server communication, use API keys instead of JWT tokens. Pass the key in the X-API-Key header.

curl

See API Keys Reference for creating and managing keys.

CLI Login

The CLI authenticates via gRPC using email/password or browser-based login. After successful authentication, an API key is automatically created and stored in ~/.hookwatch/config.yaml.

Interactive

hookwatch login

Prompts for email and password

Browser

hookwatch login --browser

Opens browser, callback to local server

Error Responses

StatusErrorDescription
401UnauthorizedInvalid or expired access token
400Bad RequestInvalid email or password format
409ConflictEmail already registered

Best Practices

  • Store tokens securely (never in plain text or local storage in production)
  • Implement automatic token refresh before expiration
  • Handle 401 responses by refreshing the token and retrying the request
  • Clear both tokens on logout to prevent session hijacking

Related