# Create and use an API Key


If you already have a full Key and a Subscription ID, go to [retrieve data](/api/api-data). They are different values: the Key authenticates your organization within its allowed scope; the Subscription ID selects the data to read. A Campaign ID is not a substitute for a Subscription ID.

## Check the organization and credential manager

Open [API Keys](https://developer.humanbased.ai/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

1. Choose **Create API Key** and enter a recognizable **Name**. An active Key in the same organization cannot share that name.
2. Choose an expiry: **7d**, **30d**, **90d**, **1y**, or **Never**; the default is 90 days.
3. 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.
4. 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**.
5. Copy the complete value from **Your new API key** into the organization's approved secret store. The portal displays the full value only once.
6. 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 task 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](/api/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:

```http
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](/help/support) before repeatedly creating Keys |

Once the complete Key and matching Subscription ID are ready, [make a small read](/api/api-data).