If you already have a full Key and a Subscription ID, go to retrieve data. They are different values: the Key authenticates your organizationThe Developer-side unit that holds Campaigns, data access, and funds within its allowed scope; the Subscription ID selects the data to read. A CampaignA developer's data-production project and its settings ID is not a substitute for a Subscription ID.
Check the organization and credential manager
Open API Keys from the Developer portal's account-and-organization menu. Confirm the active organization. Any member of that organization can create a Key; a creator can revoke their own Key, and an Owner or Admin can revoke any of the organization's Keys. The person who builds the integration does not need a changed role.
Create a data-read Key
- Choose Create API Key and enter a recognizable Name. An active Key in the same organization cannot share that name.
- Choose an expiry: 7d, 30d, 90d, 1y, or Never; the default is 90 days.
- Under Permissions → Data, enable data access. With no source selected, this covers every subscription the organization has now or creates later. To narrow the Key, expand Limit this key to specific subscriptions or campaigns, then actually select an eligible owned Campaign under Campaign access or an existing subscription under Subscription access. Opening the picker without selecting anything leaves the broad grant in place.
- Review the organization, access scope, and expiry. If a data-use agreement is required, read it and complete that separate step before selecting Create key.
- Copy the complete value from Your new API key into the organization's approved secret store. The portal displays the full value only once.
- Back in the list, inspect Scope, Status, and Expires. Under Pull from, find the source and copy its
subscription_id.
In the narrowed Data picker, Campaign access can include this organization's live, paused, or finished Campaigns, up to 25 per Key; drafts and archived Campaigns are not offered as data sources. Creating the Key creates or reuses the corresponding subscription. A Campaign marked partial reuses an existing narrower subscription and does not widen its taskA specific item a contributor claims or enters or filter scope. External data requires an existing subscription under the applicable terms.
Create a Campaign configuration Key
The same form has a separate Permissions → Campaigns area. Choose Read (campaign:read) to inspect Campaign definitions. Choose Write (campaign:author) to validate, plan, or apply a candidate; the form also selects Read so the caller can inspect the result. The manager's editable Campaigns determine the Key's write reach when it is created; a later Campaign is not automatically added to that write scope. The Data area's Campaign access picker narrows delivered records and does not grant Campaign editing.
Select Launch (campaign:launch) only for an integration that must propose a launch. It also selects Read and Write and requires a positive Spend cap with a daily or monthly window. A person must still confirm the specific launch proposal. After creation, call GET /api/v1/auth/whoami with the Key and check its organization, scopes, and managed_campaign_ids before using the Campaign API. Ask the Owner or Admin for a replacement Key if the grant or Campaign scope is wrong; changing Data access will not repair an authoring permission.
A Key with Write or Launch lasts at most 90 days, so the form locks 1y and Never. Arrange a replacement before it expires, or the programs that depend on it are refused afterwards; read-only and data Keys keep every expiry option.
Use, rotate, or revoke
Use the credential only from a controlled server or secret manager. Send it in the request header:
Authorization: Bearer <API_KEY>A Key starts with hb_live_sk_. Add that prefix to your secret scanner so a Key committed by mistake is caught.
The creator need not remain signed in for programmatic requests. Check both Status and Expires; Active does not override an expiry. If the full Key is lost, an authorized credential manager must create a replacement, update consumers, and revoke the old Key. Revoke affects every program still using it. Do not put a complete Key in a browser URL, public client, screenshot, or documentation.
| Problem | First check |
|---|---|
| No creation control | Active organization and sign-in; confirm both, then contact support if the control is still missing |
| Create key disabled | Name, at least one Permissions grant, a positive spend cap if Launch is selected, and whether the list loaded |
| Campaign missing | Organization, ownership, and Campaign state |
| Only a masked Key remains | The full value cannot be shown again. Create a replacement Key, update the programs that use it, then revoke the old one |
| Agreement or service error | Keep the message and contact support before repeatedly creating Keys |
Once the complete Key and matching Subscription ID are ready, make a small read.