Authentication

WebhookRelay supports two authentication methods: JWT tokens and API keys.

JWT Tokens

JWT tokens are obtained by logging in and are used for browser-based access.

Login

curl -X POST https://api.webhookrelay.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "displayName": "John Doe"
  },
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2024-01-22T10:30:00Z"
}

Using JWT Tokens

Include the token in the Authorization header:

curl https://api.webhookrelay.com/api/organizations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Refresh

Tokens expire after 7 days. Refresh before expiration:

curl -X POST https://api.webhookrelay.com/api/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

Logout

curl -X POST https://api.webhookrelay.com/api/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

API Keys

API keys are recommended for programmatic access. They don't expire and can be scoped to specific permissions.

Creating an API Key

curl -X POST https://api.webhookrelay.com/api/organizations/{orgId}/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["sources:read", "events:write"]
  }'

Response:

{
  "id": "key_abc123",
  "name": "CI/CD Pipeline",
  "key": "whr_live_abc123xyz...",
  "scopes": ["sources:read", "events:write"],
  "createdAt": "2024-01-15T10:30:00Z"
}

WARNING

The full API key is only shown once. Store it securely!

Using API Keys

Include the API key in the Authorization header:

curl https://api.webhookrelay.com/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer whr_live_abc123xyz..."

API Key Prefixes

Prefix	Environment
whr_live_	Production
whr_test_	Test/sandbox

Available Scopes

Scope	Description
sources:read	Read sources
sources:write	Create/update/delete sources
destinations:read	Read destinations
destinations:write	Create/update/delete destinations
routes:read	Read routes
routes:write	Create/update/delete routes
events:read	Read events
events:write	Replay events
deliveries:read	Read deliveries
analytics:read	Read analytics data
admin	Full access

Managing API Keys

List API Keys

curl https://api.webhookrelay.com/api/organizations/{orgId}/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN"

Revoke API Key

curl -X DELETE https://api.webhookrelay.com/api/organizations/{orgId}/api-keys/{keyId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Organization Context

All API requests (except auth endpoints) require an organization context. The organization ID is included in the URL path:

/api/organizations/{orgId}/...

Getting Your Organization ID

curl https://api.webhookrelay.com/api/organizations \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "data": [
    {
      "id": "org_abc123",
      "name": "My Company",
      "slug": "my-company",
      "plan": "pro"
    }
  ]
}

Security Best Practices

For JWT Tokens

1. Store securely: Use secure, HTTP-only cookies in browsers
2. Short expiration: Tokens expire after 7 days
3. Refresh proactively: Refresh tokens before they expire
4. Logout on security events: Logout after password changes

For API Keys

1. Use scoped keys: Only grant necessary permissions
2. Rotate regularly: Rotate keys periodically
3. Use environment variables: Never commit keys to code
4. Monitor usage: Review API key activity in the dashboard
5. Revoke unused keys: Delete keys that are no longer needed

Environment-Specific Keys

Create separate API keys for each environment:

# Production key
curl -X POST .../api-keys \
  -d '{"name": "Production API", "scopes": ["admin"]}'

# Staging key (read-only)
curl -X POST .../api-keys \
  -d '{"name": "Staging API", "scopes": ["sources:read", "events:read"]}'

Error Responses

401 Unauthorized

Missing or invalid authentication:

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

403 Forbidden

Valid authentication but insufficient permissions:

{
  "error": "Forbidden",
  "message": "API key does not have required scope: sources:write"
}

Example: Complete Auth Flow

// 1. Login to get JWT
const loginResponse = await fetch('https://api.webhookrelay.com/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password'
  })
});
const { token, user } = await loginResponse.json();

// 2. Get organizations
const orgsResponse = await fetch('https://api.webhookrelay.com/api/organizations', {
  headers: { 'Authorization': `Bearer ${token}` }
});
const { data: orgs } = await orgsResponse.json();
const orgId = orgs[0].id;

// 3. Create an API key for programmatic use
const keyResponse = await fetch(`https://api.webhookrelay.com/api/organizations/${orgId}/api-keys`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My App',
    scopes: ['sources:read', 'events:read']
  })
});
const { key } = await keyResponse.json();

// 4. Use API key for subsequent requests
const sourcesResponse = await fetch(`https://api.webhookrelay.com/api/organizations/${orgId}/sources`, {
  headers: { 'Authorization': `Bearer ${key}` }
});