Authentication

HowdyBell supports two authentication methods: API keys for direct integrations and OAuth tokens for marketplace apps. Both methods use the Authorization header.

API Keys

API keys are the standard method for server-to-server communication. They are scoped to a specific workspace.

Key Format

Keys start with the prefix hb_live_ followed by 40 random characters. The total length is 48 characters.

Example: hb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Usage

Include the key in the Authorization header using the Bearer scheme.

curl -X GET "https://howdybell.com/api/v1/locations" \
  -H "Authorization: Bearer hb_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Security Notes

1. The plaintext key is never stored on the server. Only a SHA-256 hash is kept.
2. If a key is missing, unknown, or revoked, the API returns a 401 status with the body {"error": "invalid_api_key"}.
3. You cannot distinguish between a revoked key and a non-existent key. This prevents attackers from probing for valid keys.
4. Rotate keys immediately if you suspect a leak.

OAuth Tokens

Marketplace apps use OAuth 2.0 to access user data. The access token is issued via the Issue an access token endpoint.

Token Format

OAuth tokens do not start with hb_live_. They are opaque strings generated by the OAuth server.

Usage

Use the same Authorization header format as API keys.

curl -X GET "https://howdybell.com/api/v1/contacts?location_id=101" \
  -H "Authorization: Bearer <oauth_access_token>"

Scoping

OAuth tokens are locked to a specific location. If the token is issued for location_id 101, any request to a different location returns a 404 error with {"error": "location.not_found"}.

Note: Draft apps can only access data within their own developer workspace. Published apps can access data for any workspace that has installed the app.

Error Handling

All authentication failures return a 401 status code. The response body is consistent across both methods:

{
  "error": "invalid_api_key"
}

This response does not reveal whether the key was invalid, revoked, or missing. Always check the status code first.

Best Practices

1. Store keys in environment variables or a secrets manager.
2. Never commit keys to version control.
3. Use separate keys for development and production environments.
4. Monitor API usage to detect unusual activity.
5. Revoke keys immediately after rotation.