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.

Choose a name that identifies the consumer, such as Looker dashboard or Nightly rankings export. Grant Read for the public /v1/api/* routes. The other available permissions apply to separate WordPress integration routes and do not add REST API endpoints.

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
`read`	Grants `GET /v1/api/*`
`write`	Does not grant the public read routes
`audit`	Applies to separate WordPress audit routes
`content`	Applies to separate WordPress content routes
Empty or unknown permissions	Grants nothing

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 `read`, 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.