Skip to main content
Skip to main content
Helix
Book a briefing →

API Authentication

All Helix API requests require authentication using an API key. This guide explains how to obtain and use your API key to access the platform.

Overview​

The Helix API uses API key authentication via the Authorization header. Each API key belongs to your organization: it can call every endpoint on the resources your organization owns and, on the feeds it subscribes to, read them and submit feedback on their items but not change them.

Obtaining an API Key​

API keys are provisioned by the Helix team. Contact support to request an API key.

Using Your API Key​

Authentication Header​

Include your API key in the Authorization header of every API request using the Bearer authentication scheme:

Authorization: Bearer YOUR_API_KEY

Example Requests​

curl https://api.feeds.onhelix.ai/feeds/news \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication Errors​

401 Unauthorized​

If your API key is invalid or missing, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Authentication failed for strategy: api-key"
  }
}

Common causes:

  • Missing Authorization header
  • Incorrect API key format
  • Expired or revoked API key
  • Using HTTP instead of HTTPS

Solutions:

  1. Verify your API key is correct
  2. Ensure the Authorization header is properly formatted: Bearer YOUR_API_KEY
  3. Check that you're using HTTPS, not HTTP

403 Forbidden​

If you're authenticated but don't have permission to change a resource, such as a write to a feed your organization subscribes to but does not own:

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Access denied to NewsFeed with id '550e8400-e29b-41d4-a716-446655440000'"
  }
}

A feed's filters belong to its owner: a subscriber gets 403 PERMISSION_DENIED on every filter route, reads included.

Two other 403 codes refuse a change the rules do not allow: BUILT_IN_PROCESSOR (changing or archiving one of our built-in processors) and OPT_IN_NOT_EDITABLE (editing an opt-in filter).

404 Not Found​

A resource that belongs to another organization, and that yours does not subscribe to, is a 404 NOT_FOUND, the same as one that does not exist.

API Key Scopes​

Each API key has access to:

  • News feed endpoints: Create, read, update, and delete news feeds
  • Event feed endpoints: Create, read, update, and delete event feeds
  • Feed configuration endpoints: Manage your processors, your feeds' filters and sources, and read the opt-in filters
  • Parse endpoints: Extract structured content from URLs or HTML
  • Fact-checking endpoints: Submit and retrieve fact-check requests
  • Deep research endpoints: Create and manage research tasks, stream results
  • Feed item endpoints: Retrieve content from your feeds
  • Event delivery endpoints: Configure destinations and subscriptions for real-time event delivery