Ahrefs User Management API Guide

Auth method: API Key (Bearer token) for direct Enterprise API v3 access; OAuth 2.0 Authorization Code flow for Ahrefs Connect third-party integrations

Setup steps

1. Ensure you are on the Ahrefs Enterprise plan.
2. Go to Account Settings > API Keys in the Ahrefs dashboard.
3. Create a new API key (workspace owners and admins only).
4. Optionally set a per-key API unit usage limit.
5. Include the key in all requests as: Authorization: Bearer YOUR_API_KEY.
6. For Ahrefs Connect (third-party apps): Submit an app application at ahrefs.com/api/integrations, implement OAuth 2.0 Authorization Code flow, redirect users to the authorization URL, exchange the code for a token via POST https://ahrefs.com/oauth2/token.php.

Required scopes

User object field mapping is not yet verified for this app.

Endpoint coverage is not yet verified for this app.

• Rate limits: Ahrefs API v3 uses an API unit consumption model rather than a traditional request-per-second rate limit. All requests consume API units included in the Enterprise package. The minimum cost per request is 50 units; total cost scales with the number of rows returned and fields requested. A free limited set of test queries is available on all plans without consuming units.
• Rate-limit headers: Yes
• Retry-After header: Unknown
• Rate-limit notes: Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are present in API responses per community documentation, though Ahrefs' official v3 docs do not explicitly enumerate header names. The primary throttle mechanism is API unit depletion, not request frequency. Workspace owners/admins can cap unit usage per API key from Account Settings.
• Pagination method: offset
• Default page size: Not documented
• Max page size: Not documented
• Pagination pointer: offset / limit

• Webhooks available: No
• Webhook notes: No webhook functionality is documented in the official Ahrefs API v3 reference or help center. The API is a pull-only REST API.
• Alternative event strategy: Implement scheduled polling against Ahrefs API v3 endpoints to detect changes in SEO data.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: Not documented

• Supported operations: Create Users (assign user in IdP → auto-added to Ahrefs workspace), Deactivate/Remove Users (unassign user in IdP → removed from Ahrefs workspace), Update Attributes

Limitations:

• Enterprise plan required; not available on Lite, Standard, or Advanced plans.
• SAML SSO must be configured before SCIM can be enabled.
• SCIM setup must be initiated through Ahrefs support - no self-serve SCIM configuration UI documented.
• SCIM endpoint URL and bearer token are not publicly documented; provided by Ahrefs support during onboarding.
• Workspace owner and admins always retain email/password login access even when SSO-only mode is enforced, to allow recovery from IdP failure.
• Supported IdPs confirmed: Okta and Microsoft Entra ID. Google Workspace and OneLogin not confirmed.
• No public documentation of group provisioning support.

The two supported automated provisioning paths are Okta and Microsoft Entra ID via SCIM 2. 0.

In both cases, the flow is: confirm Enterprise plan and active SAML SSO, contact Ahrefs support to obtain SCIM credentials, configure the SCIM integration in the IdP, then assign or unassign users to control workspace membership.

Okta processes assignments in near real-time; Entra ID runs a sync cycle approximately every 40 minutes and does not support nested group provisioning.

A third scenario - direct API v3 access for SEO data - uses Bearer token auth created in Account Settings > API Keys, with unit costs starting at a minimum of 50 units per request and scaling with rows and fields returned. API v2 was fully discontinued November 1, 2025; any v2 integrations are non-functional.

Provision and deprovision users via SCIM (Okta)

1. Confirm Enterprise plan and that SAML SSO is already configured with Okta.
2. Contact Ahrefs support to request SCIM enablement; obtain SCIM base URL and bearer token.
3. In Okta Admin Console, open the Ahrefs SAML app (or create a new SCIM app integration).
4. Under Provisioning > Integration, enter the SCIM base URL and bearer token provided by Ahrefs support.
5. Enable provisioning actions: Create Users, Update User Attributes, Deactivate Users.
6. Assign users or groups to the Ahrefs app in Okta - they are automatically added to the Ahrefs workspace.
7. Unassign a user in Okta - they are automatically removed from the Ahrefs workspace.

Watch out for: SCIM setup is not self-serve; Ahrefs support must enable it. Workspace owners/admins always retain credential login even under SSO-only enforcement.

Provision and deprovision users via SCIM (Microsoft Entra ID)

1. Confirm Enterprise plan and that SAML SSO is already configured with Entra ID.
2. Contact Ahrefs support to request SCIM enablement; obtain SCIM base URL and bearer token.
3. In Azure Portal, go to Microsoft Entra ID > Enterprise Applications > select the Ahrefs app.
4. Select Provisioning > Get started, set Provisioning Mode to Automatic.
5. Enter the SCIM base URL as Tenant URL and the bearer token as Secret Token.
6. Test the connection, then Save.
7. Assign users or groups to the app - Entra ID syncs them to the Ahrefs workspace every ~40 minutes.
8. Remove a user assignment in Entra ID - the user is deprovisioned from the Ahrefs workspace.

Watch out for: Entra ID does not support provisioning nested groups. Microsoft's sync cycle runs approximately every 40 minutes, not in real time.

Authenticate and query Ahrefs API v3 (Enterprise direct)

1. Log in to Ahrefs as a workspace owner or admin.
2. Navigate to Account Settings > API Keys and create a new API key.
3. Optionally set a unit usage cap on the key.
4. Make requests to https://api.ahrefs.com/v3/{endpoint} with header: Authorization: Bearer YOUR_API_KEY.
5. Monitor unit consumption via the /subscription/limits-and-usage endpoint (free, no units consumed).

Watch out for: API v3 exposes only SEO data endpoints (backlinks, keywords, rank tracking, site audit, etc.). There are no user-management or workspace-admin endpoints. Unit costs scale with rows and fields returned; minimum 50 units per request.

The primary integration trap is assuming Ahrefs API v3 can manage users - it cannot. The API exposes only SEO data endpoints. Teams that build user lifecycle automation against the v3 API will find zero applicable endpoints and must pivot entirely to SCIM.

A second trap is the support-gated SCIM setup: there is no self-serve toggle, and the SCIM endpoint URL and bearer token are not publicly documented, creating an unpredictable activation timeline.

SSO-only enforcement does not fully lock out credential-based login - workspace owners and admins always retain email/password access as a failsafe, which is a caveat for security posture reviews.

No official SDKs are published for API v3, and rate limiting is unit-based rather than request-frequency-based, meaning high-column or high-row queries can deplete allocations rapidly without triggering conventional rate limit errors.