Authentication & Keys

Authenticate your API requests securely using high-entropy bearer tokens with granular scopes, IP allowlists, and project-level restrictions.

Key Format & Storage

TrackSERPs issues API keys formatted as:

ts_live_<8-char prefix>_<32-char secret> for live production environments.
ts_test_<8-char prefix>_<32-char secret> for sandbox / test environments.

Tokens are generated using cryptographically secure random bytes (base62). TrackSERPs stores only a SHA-256 hash and the public prefix. The secret is displayed once upon creation and cannot be retrieved again.

Authorization Header

Provide your API key in the standard Authorization header:

HTTP Header

Authorization: Bearer ts_live_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Security rule: API keys sent in URL query strings (e.g. ?api_key=...) are immediately rejected with 400 key_in_query and are never logged. Always pass keys in the Authorization header.

Available Scopes

Every API key has one or more assigned scopes that restrict which endpoints it can call. Write scopes require an active plan with write access (Growth, Pro, or Agency):

Scope	Description	Permitted Operations
`rankings:read`	Read-only access across the account. Always enabled on all keys.	`GET /account`, `GET /projects`, `GET /locations`, `GET /rankings/`, `GET /volume/`, `GET /runs/*`
`keywords:write`	Create, update, and archive keywords in projects.	`POST /projects/:id/keywords`, `DELETE /projects/:id/keywords/:id`
`runs:write`	Trigger manual rank check runs and dry-run calculations.	`POST /projects/:id/runs`
`shares:write`	Enable, update, or regenerate public read-only share links.	`PUT /projects/:id/share`
`webhooks:write`	Create, update, test, and delete webhook subscriptions.	`POST /webhooks`, `PATCH /webhooks/:id`, `DELETE /webhooks/:id`

Key Restrictions

1. Project Restrictions

You can bind an API key to a specific list of project IDs. When calling endpoints for a project outside this list, the API responds with 404 not_found (rather than 403) to prevent probing or ID enumeration.

2. IP Allowlists

Restrict requests to designated static IPv4 or IPv6 addresses or CIDR subnets (e.g. 198.51.100.14 or 203.0.113.0/24). Requests from unauthorized IPs receive 403 ip_not_allowed.

3. Expiration

Set an optional expiration timestamp on any key. Calls made after expiration immediately receive 401 key_expired.

Key Rotation with Grace Periods

When rotating an existing key in production, you can configure an overlap grace period (0 hours, 1 hour, 24 hours, or 7 days). The old key remains valid until the grace period elapses, allowing you to update client environments without downtime.

Test Mode

Keys prefixed with ts_test_ operate in isolated test mode:

Reads return synthetic demo data from the demo project.
Writes validate schemas and return realistic success envelopes without writing to the database or triggering DataForSEO calls.
Never consume account check credits.
All responses carry the HTTP header X-TrackSERPs-Test-Mode: true.

Test Mode Request

curl -X GET "https://api.trackserps.com/v1/account" \
  -H "Authorization: Bearer ts_test_demo123_sec456" \
  -I

# Response headers include:
# X-TrackSERPs-Test-Mode: true