Authentication and API keys

Every public REST request must carry a SearchChamp API key. API keys are organization credentials: they are not tied to the current permissions of the person who created them.

Create a key

Open API Keys

In SearchChamp, open Settings → API Keys. Creating, listing, and revoking keys requires the organization-level Manage API keys permission, normally held by an owner or account admin.

Name and scope the key

Choose a name that identifies the consumer, such as Looker dashboard or Nightly rankings export.

Grant read for the public GET /v1/api/* routes. Grant write only if the integration must change an article or research-session status — write also grants the WordPress content routes. See permission behavior below, which is worth reading before you reuse an existing key.

Choose an expiry

If you do not choose an expiry, the key expires after 365 days. You can choose a shorter lifetime or a date up to 730 days from creation. The organization can hold at most 50 active API keys.

Copy the key once

The plaintext value begins with atl_ and is shown only in the creation response. SearchChamp stores its hash, not the plaintext. If you lose it, revoke it and create another.

Send the key

Bearer authentication is the recommended form:

Authorization: Bearer atl_your_key_here

The API authorizer also accepts the key in X-API-Key, but using the bearer header keeps integrations consistent and avoids tools that treat X-API-Key specially.

curl --get 'https://api.searchchamp.com/v1/api/keywords' \
  --header "Authorization: Bearer $SEARCHCHAMP_API_KEY" \
  --data-urlencode 'site=example.com'

Do not send a browser-session JWT. The public routes deliberately require an API key; a valid web session still receives 403 Forbidden here.

Permission behavior

API-key permission	Public REST access	Also grants
`read`	`GET /v1/api/*` — every public read route	The WordPress plugin status/projects/keywords routes
`write`	*`PATCH /v1/api/`** — the article and research-session status updates	`POST /v1/wp/content/*`, the WordPress content routes
`audit`	None	Separate WordPress audit routes
`content`	None	Separate WordPress content routes
Empty or unknown permissions	None	Nothing

read does not grant PATCH, and write does not grant GET. An integration that both reads and publishes needs a key holding both.

`write` now covers more than it used to — check your existing keys

write previously granted only the WordPress content routes. It now also grants PATCH /v1/api/*, the article and research-session status updates.

This applies to keys that already exist. A key issued for the WordPress plugin, carrying write, can call the new status routes today without being re-issued and without anyone re-approving it.

It matters more than it may look, because SearchChamp's own key-creation screen does not ask you to choose permissions: a key created there is granted read, write, audit, and content. Unless you created a key through the API with an explicit narrower permissions array, assume it holds write.

The grant is still fully gated on everything else — the credential must be an API key rather than a browser session, the organization must be on Pro/Business or above, every tenancy check still applies, and only {"status":"published"} is ever accepted. Nothing here can publish to a CMS. But if a consumer should not be able to change a status, issue it a read-only key and revoke the broad one rather than relying on it not knowing the route exists.

To create a narrowly scoped key, send an explicit permissions array when calling the key-creation API:

{ "name": "Looker dashboard", "permissions": ["read"] }

Store and rotate keys safely

Put the key in an environment variable or secret manager, not a source file.
Never place it in a URL, query parameter, screenshot, ticket, browser bundle, or repository.
Give each integration its own key so you can revoke one consumer without interrupting others.
Rotate before expiry and remove the old key after the new consumer succeeds.
Treat logs and shell history as sensitive; avoid commands that put the plaintext key directly in command arguments.

Revoke a key

Open Settings → API Keys, choose the key by name/prefix, and revoke it. Revocation is immediate. The key remains in SearchChamp's audit record but can no longer authenticate. A second revoke behaves like a missing key rather than reactivating it.

Authentication failures

Status	Meaning
`401 Unauthorized`	The key is missing, malformed, unknown, expired, or revoked.
`403 Forbidden`	The credential is not an API key, the key lacks the permission the route needs (`read` for `GET`, `write` for `PATCH` — the latter reports `WRITE_PERMISSION_REQUIRED`), the plan is below Pro, or the organization usage ceiling is reached.
`503 Service Unavailable`	SearchChamp could not enforce the request limit safely. Retry later; access is denied while the limiter is unavailable.

See Errors, limits, and usage for the response envelope and retry rules.

On this page