HooksDash
Get Started

Authentication

Learn how to authenticate API requests

HooksDash API supports two authentication methods depending on your use case.

Authentication Methods

1. JWT Bearer Token (Web Application)

Used by the web dashboard. Authentication is handled automatically by Clerk.

Header:

Authorization: Bearer <JWT_TOKEN>

Usage:

All authenticated web API endpoints require this header. The JWT token is automatically included by the frontend when making API requests.

Example:

curl -X GET https://hooksdash-api.ibadsiddiqui.dev/api/endpoints \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. API Key (CLI and Programmatic Access)

Used by the CLI tool and for direct API access outside the web application.

Header:

X-API-Key: hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usage:

API keys are prefixed with hd_ and are used for CLI authentication and direct API access.

Example:

curl -X GET https://hooksdash-api.ibadsiddiqui.dev/api/users/validate \
  -H "X-API-Key: hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Getting Your API Key

Via Web Dashboard

  1. Log in to hooksdash.ibadsiddiqui.dev
  2. Navigate to Settings
  3. Go to API Keys section
  4. Copy your API key or regenerate a new one

Via CLI

The CLI automatically manages your API key after authentication:

hooksdash login

This opens a browser window for authentication and stores your API key locally.

API Endpoints

Validate API Key

Validates an API key and returns user information. Used by the CLI on startup.

GET /api/users/validate

Headers:

X-API-Key: hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Response:

{
  "email": "user@example.com",
  "tier": "FREE"
}

Status Codes:

  • 200 OK - API key is valid
  • 401 Unauthorized - Invalid or missing API key

Example:

curl -X GET https://hooksdash-api.ibadsiddiqui.dev/api/users/validate \
  -H "X-API-Key: hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Get API Key

Retrieves the current user's API key. Requires JWT authentication.

GET /api/users/api-key

Headers:

Authorization: Bearer <JWT_TOKEN>

Response:

{
  "apiKey": "hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Status Codes:

  • 200 OK - API key returned
  • 401 Unauthorized - Invalid or missing JWT token

Example:

curl -X GET https://hooksdash-api.ibadsiddiqui.dev/api/users/api-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Regenerate API Key

Generates a new API key and invalidates the old one. Requires JWT authentication.

⚠️ Warning: This will invalidate your existing API key. Update your CLI and any scripts using the old key.

POST /api/users/api-key/regenerate

Headers:

Authorization: Bearer <JWT_TOKEN>

Response:

{
  "apiKey": "hd_yyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

Status Codes:

  • 200 OK - New API key generated
  • 401 Unauthorized - Invalid or missing JWT token

Example:

curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/users/api-key/regenerate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

CLI Authentication Flow

The CLI uses a secure OAuth-like flow for authentication:

1. Create CLI Session

Creates a new authentication session for the CLI.

POST /api/auth/cli-session

No authentication required.

Response:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "authUrl": "https://hooksdash.ibadsiddiqui.dev/cli-auth?session=550e8400-e29b-41d4-a716-446655440000"
}

Status Codes:

  • 201 Created - Session created

Example:

curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/auth/cli-session

2. Poll CLI Session Status

Checks if the user has completed authentication in the browser.

GET /api/auth/cli-session/:sessionId

Parameters:

  • sessionId (path) - The session ID from step 1

No authentication required.

Response (Pending):

{
  "status": "pending"
}

Response (Completed):

{
  "status": "completed",
  "apiKey": "hd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Response (Expired):

{
  "status": "expired"
}

Status Codes:

  • 200 OK - Session status returned

Example:

curl -X GET https://hooksdash-api.ibadsiddiqui.dev/api/auth/cli-session/550e8400-e29b-41d4-a716-446655440000

3. Complete CLI Session

Called by the web application after the user authenticates in the browser. Marks the session as completed and associates it with the user's API key.

POST /api/auth/cli-session/:sessionId/complete

Parameters:

  • sessionId (path) - The session ID to complete

Headers:

Authorization: Bearer <JWT_TOKEN>

Response:

{
  "message": "CLI session completed successfully"
}

Status Codes:

  • 200 OK - Session completed
  • 404 Not Found - Session not found or expired
  • 401 Unauthorized - Invalid or missing JWT token

Example:

curl -X POST https://hooksdash-api.ibadsiddiqui.dev/api/auth/cli-session/550e8400-e29b-41d4-a716-446655440000/complete \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

CLI Authentication Flow Diagram

┌─────────┐                                    ┌─────────────┐
│   CLI   │                                    │  Browser    │
└────┬────┘                                    └──────┬──────┘
     │                                                │
     │ 1. POST /auth/cli-session                     │
     ├──────────────────────────────────────►        │
     │                                                │
     │ ◄──────────────────────────────────────       │
     │   { sessionId, authUrl }                      │
     │                                                │
     │ 2. Open browser with authUrl                  │
     ├───────────────────────────────────────────────►
     │                                                │
     │                                     3. User authenticates
     │                                                │
     │                                     4. POST /auth/cli-session/:id/complete
     │                                                │
     │ 5. Poll GET /auth/cli-session/:id             │
     ├──────────────────────────────────────►        │
     │                                                │
     │ ◄──────────────────────────────────────       │
     │   { status: "pending" }                       │
     │                                                │
     │ 6. Poll again...                              │
     ├──────────────────────────────────────►        │
     │                                                │
     │ ◄──────────────────────────────────────       │
     │   { status: "completed", apiKey: "..." }      │
     │                                                │
     │ 7. Store API key locally                      │
     │                                                │

Security Best Practices

API Key Storage

DO:

  • Store API keys in environment variables or secure credential managers
  • Use different API keys for different environments (dev, staging, prod)
  • Rotate API keys regularly
  • Revoke API keys immediately if compromised

DON'T:

  • Commit API keys to version control
  • Share API keys in public channels
  • Use the same API key across multiple projects
  • Embed API keys in client-side code

Token Refresh

JWT tokens issued by Clerk expire after 1 hour. The web application automatically handles token refresh. If you're building a custom integration, ensure you handle token expiration and refresh.

HTTPS Only

Always use HTTPS in production. The API will reject requests over HTTP in production environments.

Troubleshooting

401 Unauthorized

Possible causes:

  • Missing authentication header
  • Invalid or expired JWT token
  • Invalid or revoked API key

Solution:

  • Check that you're sending the correct authentication header
  • For JWT: Ensure token is valid and not expired
  • For API key: Regenerate your API key in the dashboard

403 Forbidden

Possible causes:

  • Trying to access a resource you don't own
  • Tier limit reached (e.g., maximum endpoints created)

Solution:

  • Ensure you're accessing your own resources
  • Check your tier limits and upgrade if needed

Rate Limiting

Authentication endpoints have special rate limits:

EndpointRate Limit
POST /auth/cli-session5 per minute
GET /auth/cli-session/:id30 per minute
POST /auth/cli-session/:id/complete5 per minute
GET /users/validate60 per minute
POST /users/api-key/regenerate3 per hour

These limits are designed to prevent abuse while allowing normal usage patterns.