# Ahrefs setup for PopMCP

You paste a single Ahrefs API v3 key, created in Account settings under API keys. PopMCP sends it as an Authorization: Bearer header.

- Auth: API credentials
- Setup time: 4 min
- API base URL: https://api.ahrefs.com/v3
- Credentials screen: https://app.ahrefs.com/account/api-keys
- Provider docs: https://docs.ahrefs.com/docs/api/reference/introduction

## Approval required before this works

No human approval, but Ahrefs only lets workspace owners/admins on a paid Lite plan or higher mint an API v3 key - the free Webmaster Tools tier and the $29 Starter plan cannot use the API at all.

- Typical wait: None - the key is issued instantly once you are on Lite or above
- Cost: Plan prices on ahrefs.com/pricing: Lite $129/mo, Standard $249/mo, Advanced $449/mo (monthly billing; paying annually saves up to 17%), Enterprise $1,499/mo on an annual commitment. API units are included per plan - Lite 100,000, Standard 400,000, Advanced 1,000,000, Enterprise 2,000,000 per month - with pay-as-you-go top-ups on eligible plans.
- Blocked until approved: Every billable endpoint (Site Explorer, Keywords Explorer, backlinks, batch analysis) on the free Ahrefs Webmaster Tools tier and on the $29 Starter plan - Ahrefs states API v3 is available to "Lite and higher subscription plans", so below Lite there is no key to create. Row caps also bind by tier: 100 rows/request on Lite, rising through Standard and Advanced to uncapped on Enterprise.
- Works meanwhile: On any paid plan you can create the key and run the free test queries, plus Rank Tracker, Management and Public endpoints, which cost no units.

## Before you begin

- An Ahrefs subscription on an eligible paid plan. Other plans get only a limited set of free test queries
- Workspace owner or admin role. Only those roles can create and manage API keys
- API calls burn API units from the workspace balance, so agree a budget before pointing an AI agent at it

## Get your credentials

### 1. Open Account settings and click API keys

Sign in to Ahrefs, click your avatar in the top right and choose Account settings. Click API keys in the settings sidebar.

Screen: https://app.ahrefs.com/account/api-keys

### 2. Create a key for PopMCP

Click Create API key and name it `PopMCP`. Set a Monthly API units limit if you want a cap on what the connection can spend.

Screen: https://app.ahrefs.com/account/api-keys

### 3. Copy the key before you close the dialog

Ahrefs shows the full key once. Click Copy and store it somewhere safe.

Screen: https://app.ahrefs.com/account/api-keys

### 4. Paste the key into PopMCP

Put the value in API key and connect.

## Fields PopMCP asks for

- API key (apiKey) [required]: In Ahrefs: click your avatar (top right) → Account settings → API keys → create a key (workspace owners/admins only; requires an Enterprise plan with API access). Copy it and paste here. Keys last 1 year. Stored encrypted.

## Verify

PopMCP shows Ahrefs as Connected and a domain-rating or backlinks lookup returns metrics rather than an authorization error.

## Troubleshooting

### 401 Unauthorized

Cause: Each key lasts one year from creation. The key may have expired, been deleted, or been killed because the person who created it left the workspace.

Fix: Create a fresh key in Account settings, API keys, and reconnect PopMCP with it. Set a reminder roughly 11 months out.

### 403, or no API keys item in the sidebar

Cause: You are a member rather than an owner or admin, or the plan is not one of the eligible paid plans.

Fix: Ask a workspace owner to create the key, or move the workspace to an eligible plan.

### 429 Too Many Requests

Cause: More than 60 requests in a minute from the same key.

Fix: Slow the agent down and retry with backoff. The window is a rolling minute.

### Requests suddenly fail mid-month

Cause: The key hit its monthly API-unit limit, or the workspace ran out of units.

Fix: Raise the per-key limit on the API keys page, or top up units under Limits & usage.

---

Source: https://www.docs.popmcp.com/docs/integrations/ahrefs/