API Keys and Scopes
Create API keys, limit them with scopes and a workspace binding, and keep them safe.
An API key authenticates requests to the RankDebug API. Send it in the X-API-Key header.
Creating a key
On the API Keys page, click Create API Key and set:
- Name: a label so you can tell keys apart.
- Permissions: one or more scopes, below. Grant only what the key needs.
- Workspace access: either This workspace, which binds the key to the current workspace so requests naming any other are rejected, or All workspaces, which lets the key read and write every workspace on the account.
- Expiration Date: optional. An expired key answers
401.
The full key is shown once, when it is created. Copy it then; it cannot be shown again. The API Keys page lists each key with its permissions, workspace, status and when it was last used, and lets you delete it.
Scopes
| Scope | Label in the dashboard | Grants |
|---|---|---|
workspaces | Workspaces | Listing, creating, updating and deleting workspaces, plus request logs and activity |
webhooks | Webhooks | Webhook endpoints, test events, delivery logs and redelivery |
search | Search | Search Console, Google Analytics, CDN, crawl, site check, deploy and digest reads |
deploys | Deploys | Recording deploys from CI. Write-only: it reads nothing back |
logs | Server Logs | Sending server access logs. Write-only |
ai | AI (spends credits) | AI features. Never bundled into another scope because it spends the account's AI balance |
Reading shared reports through the Reports endpoints needs a seventh scope, reports. The key form does not offer it yet.
Connections themselves stay in the dashboard: no scope lets a key connect or disconnect a data source.
Keeping keys safe
- For CI, create a key with only
deploysand bind it to the workspace. If it leaks, it can record deploys and nothing else. - Store keys as secrets in your CI or secret manager, never in code.
- Delete a key you no longer use. Each key's last use is shown on the API Keys page, and each workspace's Logs page lists the requests made against it for 30 days.
Related documentation
- Overview
Base URL, authentication, scopes, errors and rate limits for the RankDebug API.
- Workspaces
List, create, update and delete workspaces, and read a workspace's request logs and activity.
- Search
Search Console performance, top rows, opportunities and sitemaps for a workspace.
- Traffic
Google Analytics landing pages, acquisition and measurement health, and CDN crawler traffic, error paths and firewall rules.
- Deploys
Record deploys from CI, list them, and read one deploy with its site check, crawl and search impact.
- Site Crawls
Read crawls of the workspace website, their findings, and every page of one finding.
- Digests
Read what the latest scheduled digest email for a workspace contained.
- Reports
Read the reports shared with a workspace, their comment threads, and their PDF.