Skip to main content

Authentication

Every request to the Ranktracker REST API is authenticated with an API key. There are no OAuth flows, no session cookies, and no per-request signing — you send one long-lived key on each request and that's it.

How it works​

Send your API key in the Authorization header. There is no Bearer prefix — the header value is the key itself:

Authorization: tkn_usr_your_api_key_here

A full request looks like this:

curl https://api.ranktracker.com/v1/domains \
  -H "Authorization: tkn_usr_your_api_key_here"

The same header goes on every endpoint under /v1, for reads and writes alike.

import requests

headers = {"Authorization": "tkn_usr_your_api_key_here"}

resp = requests.get("https://api.ranktracker.com/v1/domains", headers=headers)
resp.raise_for_status()
print(resp.json()["data"])
const resp = await fetch("https://api.ranktracker.com/v1/domains", {
  headers: { Authorization: "tkn_usr_your_api_key_here" },
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const { data } = await resp.json();
console.log(data);

:::note Base URL All examples use the production base URL https://api.ranktracker.com, and every endpoint lives under /v1 (for example https://api.ranktracker.com/v1/domains). :::

Creating and revoking keys​

API keys are created and managed in the Ranktracker app, not through this API.

  1. Sign in at app.ranktracker.com.
  2. Open your account settings and go to the API keys section.
  3. Create a key, then copy it. Store it somewhere safe — treat it like a password.
  4. To revoke a key, delete it from the same screen. The key stops working immediately.

What a key can and cannot do​

Be aware of these properties before you build against the API:

  • No scopes. A key grants access to everything your account and plan can do through the API — all of your domains, keywords, competitors, tags, SERP data, and account usage. You cannot mint a read-only or resource-limited key.
  • No expiry. A key stays valid until you delete it. It will not rotate or time out on its own.
  • Account-scoped. A key only ever sees data in the account that owns it. Requests for domains or keywords in another account return 404, as if they did not exist.

:::warning Keep your key secret Because keys carry full access and never expire, a leaked key is a serious problem. Use keys server-side only — never ship one in browser JavaScript, a mobile app, or any client a user can inspect, and never commit one to source control. Load keys from environment variables or a secrets manager. :::

Rotating a key​

There is no in-place "roll" operation. To rotate:

  1. Create a new key in the app.
  2. Deploy it to your integration and confirm traffic is flowing on the new key.
  3. Delete the old key in the app.

Because both keys are valid at once during step 2, you can rotate with zero downtime. Rotate immediately if you suspect a key has been exposed.

Your plan must have API access enabled​

API access is a plan-level feature. If your current plan does not include API access, authenticated requests are rejected with 403 Forbidden even when the key itself is valid.

You can confirm whether API access is on for your plan by reading GET /v1/account/usage. Its response includes an apiEnabled flag in data.attributes:

curl https://api.ranktracker.com/v1/account/usage \
  -H "Authorization: tkn_usr_your_api_key_here"
{
  "data": {
    "id": "…",
    "type": "usage",
    "attributes": {
      "apiEnabled": true,
      "keywords": { "usage": 1420, "limit": 2000, "remaining": 580 },
      "dataRows": { "usage": 8500, "limit": 12000, "remaining": 3500 }
    }
  }
}

If apiEnabled is false, upgrade your plan or contact support to turn API access on. See Usage and quota for the rest of this response.

What auth failures look like​

Errors come back in the JSON:API error envelope — an errors array where each entry has a code, a status, and a human-readable detail:

{
  "errors": [
    {
      "code": "unauthorized",
      "status": 401,
      "detail": "Invalid or missing API key."
    }
  ]
}

The two failures you'll see most:

StatusMeaningHow to fix
401 UnauthorizedThe Authorization header is missing, malformed, or the key is wrong.Send the key with no Bearer prefix; check for stray whitespace; confirm the key still exists in the app.
403 ForbiddenThe key is valid but the request is not allowed — most commonly your plan does not have API access enabled. It also covers other forbidden actions.Check apiEnabled via /v1/account/usage; upgrade the plan if needed.

:::note A common gotcha A 403 here does not mean your key is bad — the key authenticated fine. It almost always means API access is off for your plan. Reserve 401 in your head for "the key didn't work," and 403 for "the key worked but you're not permitted." :::

A missing or invalid key is always rejected — there is no anonymous access to any /v1 endpoint.

Next steps​