API Authentication

Authenticate to the Pingward API using API keys or JWT tokens.

API Keys

API keys are the recommended way to authenticate programmatic access.

Creating an API Key

1. Go to Settings → API Keys
2. Click Create API Key
3. Enter a descriptive name
4. Copy the key immediately (it won't be shown again)

Using API Keys

Include the key in the X-API-Key header:

curl -H "X-API-Key: pw_live_abc123..." \
  https://api.pingward.com/api/tests

Key Format

API keys follow the format:

pw_live_<random>   # Production keys
pw_test_<random>   # Test/sandbox keys (future)

Key Security

• Keys are shown only once at creation
• Store keys securely (environment variables, secrets manager)
• Never commit keys to source control
• Rotate keys periodically
• Delete unused keys

JWT Tokens

JWT tokens are used for session-based authentication (web app).

Obtaining a Token

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

Response:

{
  "succeeded": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "user@example.com"
  }
}

Using JWT Tokens

Include the token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.pingward.com/api/tests

Token Expiration

JWT tokens expire after 24 hours. After expiration, obtain a new token by logging in again.

Workspace Context

All API calls operate within a workspace context:

• API keys are scoped to a specific workspace
• JWT tokens use the user's current workspace
• Switch workspaces with /api/auth/switch-tenant

Rate Limiting

API requests are rate limited:

• 100 requests per minute per API key
• 1000 requests per hour per API key

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706123456

Error Responses

401 Unauthorized

{
  "error": "Invalid or missing authentication"
}

Causes:

• Missing API key or token
• Invalid/expired API key
• Expired JWT token

403 Forbidden

{
  "error": "Access denied"
}

Causes:

• Valid auth but insufficient permissions
• Accessing another workspace's resources

Best Practices

Use API Keys for Automation

• CI/CD pipelines
• Scripts
• Integrations

Use JWT for Interactive Apps

• Custom dashboards
• Admin tools
• Mobile apps

Secure Key Storage

# Environment variable
export PINGWARD_API_KEY="pw_live_abc123"

# Use in script
curl -H "X-API-Key: $PINGWARD_API_KEY" ...

Rotate Keys Regularly

1. Create a new key
2. Update your applications
3. Verify they work
4. Delete the old key