Skip to main content
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, and if the broker-funder relationship doesn’t exist in the system, it will be created automatically. 
const BASE_URL = 'https://api.herondata.io';
const USER_API_KEY = 'key_xxxxxxxxx';

const response = await fetch(`${BASE_URL}/broker_submissions/api_keys/generate`, {
  method: 'POST',
  headers: {
    'x-api-key': `${USER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
  }),
});

if (!response.ok) {
  throw new Error(`Failed to generate API key: ${response.statusText}`);
}

const data = await response.json();
// ^ { broker_funder_token: 'bft_xxxxxxxxx' }

const brokerApiKey = data.broker_funder_token;
:::note 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: 
const BASE_URL = 'https://api.herondata.io';
const USER_API_KEY = 'key_xxxxxxxxx';

const response = await fetch(`${BASE_URL}/broker_submissions/api_keys`, {
  headers: {
    'x-api-key': `${USER_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`Failed to list API keys: ${response.statusText}`);
}

const apiKeys = await 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. 
const apiKeyHeronId = 'bfk_xxxxxxxxx';
const BASE_URL = 'https://api.herondata.io';
const USER_API_KEY = 'key_xxxxxxxxx';

const response = await fetch(
  `${BASE_URL}/broker_submissions/api_keys/${apiKeyHeronId}`,
  {
    method: 'DELETE',
    headers: {
      'x-api-key': `${FUNDER_API_KEY}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`Failed to delete API key: ${response.statusText}`);
}

console.log('API key successfully deleted');
// The broker will no longer be able to use this key to submit applications
:::note 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 (it belongs to a different user)

​
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.