Skip to main content

API Access

API keys let external systems authenticate with the Harmony Public API for programmatic access to workspace data.

How to access API settings​

Go to Workspace Settings > API under Security & Trust.

This opens the API Keys page, where authorized users can create, view, and delete workspace API keys.

Viewing API keys requires api-keys:read:all or api-keys:read:team. Creating keys requires api-keys:create:all. Deleting keys requires api-keys:delete:all. By default, these are admin-level permissions.

What API keys look like​

Harmony API keys start with lk_ followed by 64 lowercase hexadecimal characters.

lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The full key is shown only once when it is created. Harmony stores only a hashed version, so lost keys cannot be recovered.

Creating an API key​

  1. Go to Workspace Settings > API.
  2. Click Create API Key.
  3. Enter a clear Name, such as "Production data pipeline" or "Custom dashboard".
  4. Optionally assign a Role. If selected, the key inherits that role’s permissions. If no role is selected, the key uses default permissions.
  5. Optionally choose an Expiration Date.
  6. Click Create API Key.
  7. Copy the key immediately and store it securely.

The page may also show a rate-limit value next to the key. This is a stored display value, not the actual enforcement mechanism.

Authentication​

Send the key in the X-API-Key header on every request.

curl -X GET "https://api.heyharmony.com/v1/conversations" \
  -H "X-API-Key: lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Do not send Harmony API keys as Authorization: Bearer tokens or URL query parameters.

Permissions​

An API key’s access depends on the role assigned to it.

  • A key with an Admin-like role can access broad workspace data.
  • A custom integration role can be limited to only the resources the integration needs.
  • A key with no role uses default permissions.

Use one key per application or integration so you can rotate or delete a single key without affecting other systems.

Rate limiting​

The Public API enforces a global limit of 1,000 requests per 15 minutes per client IP, shared across all /v1/* endpoints and all API keys originating from that IP. The "rate limit" value shown next to a key in the UI is informational only — the actual enforcement is the per-IP global limit.

If the limit is exceeded, the API returns 429 Too Many Requests with informational rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset). Creating another key does not raise the limit for the same client IP — distribute load across IPs or implement client-side back-off instead.

Managing keys​

The API Keys table shows each key’s name, role, display rate limit, creation date, expiration, and actions.

Delete a key immediately if it is no longer needed or may have been exposed. Deletion is permanent, and requests using the deleted key return 401 Unauthorized.

Security best practices​

  • Store API keys in a secrets manager or environment variables.
  • Never commit API keys to source control.
  • Never share keys in screenshots, tickets, URLs, or logs.
  • Use the least-privileged role that still lets the integration work.
  • Rotate keys periodically and after any suspected exposure.

Troubleshooting​

401 Unauthorized​

  • Check that the key is correct and not truncated.
  • Use the X-API-Key header.
  • Confirm the key has not expired or been deleted.

403 Forbidden​

  • The key is valid, but its role does not allow the requested action. Review the assigned role and permissions.

429 Too Many Requests​

  • The client IP exceeded the global Public API rate limit. Back off and retry after the reset time.