Skip to content

Create an API key and authenticate

Make a key, choose its access level and expiry, send it in a header, and know what each level can do.

3 min read · Updated November 18, 2026

The HeyLeads API lets other software work with your workspace: read campaigns and results, add leads to lists and campaigns, manage tags and more. Anything you call it with needs a key. Keys belong to one workspace, and every request acts inside it.

#Create a key

  1. Open Settings, Integrations, then the HeyLeads API tile

  2. Under API keys, choose Create API key

  3. Give it a Name you'll recognise

    For example CRM sync. Make one key per tool, so you can revoke one without breaking the rest.

  4. Choose the Access level

    Read-only, Member or Admin. Pick the lowest that works.

  5. Choose when it Expires

    Never, 30 days, 90 days or 1 year.

  6. Choose Create key and copy it

    It starts with hl_live_ and is shown once. HeyLeads keeps only a scrambled copy, so a lost key can't be recovered. Make a new one and revoke the old one.

#Access levels

LevelWhat it can do
Read-onlyRead campaigns, results and A/B tests. Can't see leads or accounts, and can't change anything.
MemberRead leads and accounts, create and edit campaigns, add leads, make lists, set do-not-contact. Can't launch campaigns.
AdminAll of that, plus launch, pause and resume campaigns, manage LinkedIn accounts and manage webhooks.

A key is never an owner key: billing and deleting a workspace stay with people. A key can also never do more than the person who created it can do right now. Demote or remove them and their keys shrink or stop straight away.

#Send the key

Put it in the Authorization header of every request. The base address is https://app.heyleads.so/api/v1. Anything else gets a 401.

Check your key works
curl -s https://app.heyleads.so/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

A good answer names your workspace, your plan and the key's access level.

#Revoke or rotate a key

  1. To rotate, create the new key first and switch your tool over to it

  2. Find the old key in the list, open Key actions and choose Revoke

  3. Confirm Revoke this API key?

    Anything still using it gets a 401 on its next request. Leads, lists and campaigns it created stay in your workspace.

#Agencies: organization keys

If you run client workspaces under an organization, an organization key (hl_org_…) can create workspaces, set account caps, invite people and mint workspace keys. It never reads or writes a workspace's leads, campaigns or inbox; for that, mint a workspace key. Details are in the developer reference. To understand organizations first, see Organizations and client workspaces.

Was this article helpful?