Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.herondata.io/llms.txt

Use this file to discover all available pages before exploring further.

As a funder, you can generate and manage API keys for your broker partners. These keys allow brokers to programmatically submit applications with company details and supporting documents directly to your account through the Broker Submissions API.

​
Prerequisites

Before following this guide, you will need:
  • Access to dashboard.herondata.io via your username and password
  • Your user api_key to call the Heron API
  • The email address of the broker you want to grant API access to

​
How Broker API Keys Work

Broker API keys establish a secure, one-to-one connection between a specific broker and your funder account.
  • Keys are tied to the broker’s email domain
  • Brokers use these keys to authenticate when creating submissions
  • You maintain full control over which brokers have API access

​
Generate a Broker API Key

To create a new API key for a broker partner you’ll need to provide their email address. The broker is identified by their email domain so the domain must already correspond to an existing broker in the system. If the broker exists but isn’t yet linked to your funder account the broker-funder relationship will be created automatically.
app.py
import requests

BASE_URL = "https://app.herondata.io"
USER_API_KEY = "key_xxxxxxxxx"

response = requests.post(
  f"{BASE_URL}/api/broker_submissions/api_keys/generate",
  headers={
    "x-api-key": USER_API_KEY,
    "Content-Type": "application/json",
  },
  json={
    "email": "[email protected]"
  }
)

response.raise_for_status()

data = response.json()
# ^ { "broker_funder_token": "bft_xxxxxxxxx" }

broker_api_key = data["broker_funder_token"]

# Securely share this API key with your broker partner
print(f"Broker API Key: {broker_api_key}")
After generating the API key, securely share it with your broker partner. They will use this key to authenticate all API requests when creating submissions on your behalf.

​
Error Responses

When generating API keys, you may encounter these errors:
  • 404: Broker with the specified email domain does not exist in the system
  • 409: An API key already exists for this broker email.

​
List All Broker API Keys

You can retrieve all broker API keys associated with your funder account to see which brokers currently have API access:
app.py
BASE_URL = "https://app.herondata.io"
USER_API_KEY = 'key_xxxxxxxxx'

response = requests.get(
  f"{BASE_URL}/api/broker_submissions/api_keys",
  headers={
    "x-api-key": USER_API_KEY,
  }
)

response.raise_for_status()

api_keys = response.json()
# ^ [
#     {
#       "broker": "ABC Broker LLC",
#       "broker_funder_api_key_heron_id": "bfk_xxxxxxxxx",
#       "broker_funder_api_key_token": "bft_xxxxxxxxx"
#     }
#   ]

​
Delete a Broker API Key

To revoke a broker’s API access, delete their API key using the broker_funder_api_key_heron_id you’ve received from the GET API keys endpoint.
app.py
broker_api_key_heron_id = "bfk_xxxxxxxxx"
BASE_URL = 'https://app.herondata.io'
USER_API_KEY = 'key_xxxxxxxxx'

response = requests.delete(
  f"{BASE_URL}/api/broker_submissions/api_keys/{broker_api_key_heron_id}",
  headers={
    "x-api-key": USER_API_KEY,
  }
)

response.raise_for_status()

print("API key successfully deleted")
# The broker will no longer be able to use this key to submit applications
Once deleted, the broker will immediately lose access to submit applications using that API key. Any in-flight requests using the deleted key will fail with an authentication error.

​
Error Responses

  • 404: API key not found (may have already been deleted or invalid ID)
  • 403: You do not have permission to delete this API key

​
Managing Broker Access via Dashboard

In addition to the API, you can also manage broker API keys through the Heron Dashboard:
  1. Log in to dashboard.herondata.io
  2. Navigate to Settings on the sidebar menu
  3. Scroll to the Broker Credentials section
  4. Here you can view all active broker API keys, generate new keys, and revoke existing ones API Key Generation

​
Next Steps

After generating an API key for your broker partner, direct them to the Broker Submissions Integration guide to learn how to use the API key to submit applications programmatically.