# API key and first request

> Create an SEO Tools API key and list your projects.

Canonical: https://docs.georanker.com/docs/seo-tools-api-quickstart

Create a key in the GeoRanker platform, then list your SEO Tools projects. The project ID from that first request is what you will use in most report workflows.

## Create your API key

* Sign in to the GeoRanker platform and open the **SEO Tools** service. Select the organization you want the integration to use if you have access to more than one. [Open the SEO Tools service](https://platform.georanker.com/services/seo_app)
* Select **API keys**.

![API keys tab in the GeoRanker SEO Tools service](https://docs.georanker.com/images/readme/seo-tools-api-quickstart/seo-tools-api-keys-tab.png)

* Select **New key** to open the creation form.

![New key button on the SEO Tools API keys tab](https://docs.georanker.com/images/readme/seo-tools-api-quickstart/seo-tools-new-key.png)

* Under **Issue to**, select yourself or a teammate who has SEO Tools access. Calls made with the key carry that person's access and are attributed to them.
* Enter a **Name** you will recognize, such as `Reporting integration`. Select **Create key**. If the platform shows a replacement warning, plan to update existing integrations first. The old key stops working when the replacement reaches SEO Tools.

![SEO Tools API key form with Reporting integration in the Name field and the Create key button](https://docs.georanker.com/images/readme/seo-tools-api-quickstart/api-key-name-form.png)

* In **Copy your key now**, select **Copy**, store the key in your application's secret store, and select **Done**. The platform shows the full new key once.

![Illustrative Copy your key now confirmation showing the Copy and Done buttons and a hidden sample key](https://docs.georanker.com/images/readme/seo-tools-api-quickstart/api-key-confirmation.png)

* Wait for the key to change from **Activating** to **Active** before using it. To retire a key, select **Revoke** on the same tab.

Keys begin with `gk_` or `grk_`. Send the full key as `Authorization: Bearer YOUR_API_KEY`. The API has no login or token refresh step. Keep the key out of client-side code, Git, URLs, and support screenshots.

## Make your first request

Set `SEO_TOOLS_API_KEY` from your secret store. For a local Bash session, read it silently and export it for the examples on this site.

```bash
read -r -s -p "SEO Tools API key: " SEO_TOOLS_API_KEY
printf '\n'
export SEO_TOOLS_API_KEY
```

List active projects. This request reads campaign information without creating a report.

```bash
curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer ${SEO_TOOLS_API_KEY}" \
  --data-urlencode 'status=active' \
  'https://seoapi.georanker.com/api/projects'
```

An illustrative response contains a `projects` array. Copy the `id` for the campaign you want to use.

```json
{
  "projects": [
    {
      "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "name": "US search visibility",
      "domain": "example.com",
      "status": "active",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}
```

If the array is empty, check that you selected the right organization. You can also [create a project through the API](https://docs.georanker.com/docs/seo-tools-api-projects-and-lists#find-or-create-a-project). When you finish testing in the shell, run `unset SEO_TOOLS_API_KEY`.

## Troubleshoot a request

| What you see                | What to check                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `401 UNAUTHENTICATED`       | Check the full key, the `Bearer ` prefix in the header, and whether the key was revoked.                                                  |
| `403 Forbidden` on a write  | Check your role and report ownership. Viewers cannot create reports. Members can modify or delete reports they created.                   |
| `402 SUBSCRIPTION_PAST_DUE` | The organization's subscription is past due. Reads continue to work. Resolve the subscription before creating or changing a report.       |
| `404 Not Found`             | Verify the project or report UUID, that it belongs to the key's organization, and that you used the endpoint for the correct report type. |
| A validation error          | Read `error.code` and `error.message` when present. Check the expected field names, allowed values, and JSON wrapper before retrying.     |
| A connection error          | Check the service with the public `GET /api/health` endpoint, which needs no key.                                                         |

Pick a report to run with the project ID you just retrieved. [SEO Tools API report guide](https://docs.georanker.com/docs/seo-tools-api)
