> ## Documentation Index
> Fetch the complete documentation index at: https://devs.surferseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Get an API key for your organization and send it with every request.

Support issues the key to the owner of your organization, the Surfer account that holds your subscription, members, and workspaces, and one key acts across all of them. To see whether your plan includes API access, go to **MCP & API → API** in the app.

## Who can use the API

API access is included in the Peace of Mind and Enterprise plans and in the API add-on; some older plans include it too. Compare plans on the [pricing page](https://surferseo.com/pricing/).

Without access, the API tab reads "API access is not available on your plan" and offers an upgrade instead of a key.

## Get your API key

Support issues one API key per organization, and only to the organization owner.

**1. Sign in as the organization owner**

Open [app.surferseo.com](https://app.surferseo.com) with the owner account
of the organization that needs the key.

**2. Open the API tab**

Go to **MCP & API → API**.

**3. Open the support form**

Select **Contact Support** on the **Get your API key** card.

![The 'Get your API key' card, with the text 'Send us a quick note to get your key or have your questions answered' and a Contact Support button](https://mintcdn.com/surfer-1a8fda11/PYC_YcZDvMU0lGeA/images/api/authentication-get-api-key.png?fit=max\&auto=format\&n=PYC_YcZDvMU0lGeA\&q=85\&s=1a6c0e15893331448dbe6fb53fa07cd4)

**4. Send the request**

Send the form that opens. It is prefilled with the message "Hi, I would like to get my API key."

**5. Store the key**

When support sends the key, store it where your server code can read it,
for example in an environment variable named `SURFER_API_KEY`. Never ship it
in browser code or commit it to a repository.

> [!NOTE]
>
> Asking support to reset the key replaces it at once, for every integration
> that holds the old one. Use the same **Contact Support** button when a key is
> lost or has leaked, then update every integration together.

## Send the key with every request

Send the key in the `API-KEY` header, over HTTPS. The few requests that need no key say so on their reference page; `GET /api/v1/locations`, which lists the location names other endpoints accept, is one of them.

> [!WARNING]
>
> Surfer has no sandbox. Every request runs against your live account: reads
> count toward the rate limits, and creating a Content Editor or generating an
> article spends the same credits as in the app.

In a terminal, replace `<your key>` and run this to list the workspaces your key can reach:

```bash theme={"system"}
export SURFER_API_KEY="<your key>"
curl https://app.surferseo.com/api/v2/workspaces \
  -H "API-KEY: $SURFER_API_KEY"
```

A `200` with a `data` list confirms the key works; an empty list is still a success. Each item is a workspace, the brand or site you manage in Surfer, and carries the `id` that v2 URLs take.

[List workspaces](/api/v2/workspaces/list-workspaces) has the full response. [Requests and responses](/api/requests) covers the base URL and the formats every endpoint accepts.

Surfer MCP needs no API key; it signs in with your Surfer account ([MCP authentication](/mcp/authentication)).

## What a key can reach

The key belongs to one organization, and what it reaches differs between the two API versions:

* v2 requests act on every workspace in the organization. The workspace is named in the URL path; [Requests and responses](/api/requests) covers workspace scoping.
* v1 requests act as the organization owner the key was issued to.

## When authentication fails

For `401`, check the header and the key; for `403`, check your organization's access.

| Status | Reason | Cause | What to do |
| - | - | - | - |
| `401` | `unauthorized` | The `API-KEY` header is missing or the key is not recognized. | Check the header name and the key value, and confirm you hold the current key ([reset](#get-your-api-key) replaces it). |
| `403` | `permission_denied` | The key is valid but API access is not enabled for your organization. | Check [Who can use the API](#who-can-use-the-api). If your plan includes API access and `403` persists, write to [support@surferseo.com](mailto:support@surferseo.com). |

Both responses use the v2 error envelope with `reason` set to `unauthorized` or `permission_denied`; [Errors](/api/errors) documents the envelope and every other reason.

v1 answers both cases with the plain-text body `Access denied.`, and a v1 `403` can also mean your plan lacks the tool behind that endpoint, for example Audit or SERP Analyzer. [Migrating from v1](/api/migrating-from-v1) covers the other differences.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.