Authentication

Every request carries one credential in the Authorization header:

Authorization: Bearer <key or access token>

There are two kinds:

• An API key, for your own scripts and servers, and for MCP clients that take a header (Claude Code, Cursor, VS Code).
• An OAuth access token, for apps and AI assistants that sign in on your behalf (Claude.ai and ChatGPT connectors). You approve each app in the browser, and you can revoke it at any time.

Which key works whereCopy Anchor Link

Each product has its own keys and its own OAuth connections. They are never shared.

A key used on the wrong product gets 401 invalid_token with a message that says so.

An OAuth token is tied to the exact address it was requested for (its resource). A token for https://panel.rankshark.io/mcp/track does not work on https://panel.rankshark.io/v1/track. Request a token for each address you call.

ScopesCopy Anchor Link

A scope is a permission. A key holds every scope its product has, unless your plan is read-only. An OAuth app holds the scopes you approved.

RankShark TrackCopy Anchor Link

RankShark EnhanceCopy Anchor Link

Read-only plansCopy Anchor Link

On a read-only plan (Track Starter), keys and connected apps keep only the :read scopes. A call that needs another scope gets 403 insufficient_scope. Upgrade the plan and the same key gets its full scopes back.

The API reference shows the scope each endpoint needs.

OAuth for apps and AI assistantsCopy Anchor Link

RankShark runs an OAuth 2.1 authorization server, so MCP clients such as Claude.ai and ChatGPT can connect with a sign-in instead of a key. Most people never deal with it directly: you paste the MCP URL into the app, sign in, and approve.

What you seeCopy Anchor Link

1. The app sends you to RankShark. Sign in if you are not signed in yet.
2. If your account has several workspaces with the product, pick one.
3. Review what the app asks for. Untick anything you do not want to allow, then click Allow.

Only the workspace owner or a manager can approve an app. Connected apps are listed in the panel under Settings, API & MCP, Connected apps. Revoking one signs it out at once. Regenerating the API key does not affect connected apps.

For app developersCopy Anchor Link

The server follows the MCP authorization spec. Point your client at a resource and it can find everything else.

Resources (what a token is for), and their metadata:

Authorization server metadata: https://panel.rankshark.io/.well-known/oauth-authorization-server

How it works:

• Discovery. A request without a valid token gets 401 with a WWW-Authenticate header that names the resource metadata and the scopes:

  Copy Text

  WWW-Authenticate: Bearer resource_metadata="https://panel.rankshark.io/.well-known/oauth-protected-resource/mcp/track", scope="track:read track:write track:run track:delete track:reports"

• Client registration. Identify your client with a Client ID Metadata Document: use the HTTPS URL of your client's metadata as the client_id. Dynamic Client Registration (POST /oauth/register) also works. Only public clients are supported (token_endpoint_auth_method: none).

• Authorization code with PKCE. response_type=code, code_challenge_method=S256 is required. Send resource with the exact resource URL above. Without it, the request is for the Enhance MCP server.

• Redirect URIs must match exactly. Loopback redirects (http://127.0.0.1, http://localhost) may use any port.

• Tokens. Access tokens last one hour. Refresh tokens last 30 days and change on every use. Using an old refresh token again signs out the whole connection.

• Scopes. Ask for the scopes you need with scope. The person approving can untick some, so read the scope field of the token response.

A token request:

curl -X POST https://panel.rankshark.io/oauth/token \
  -d grant_type=authorization_code \
  -d client_id="https://app.example.com/oauth/client.json" \
  -d code="$CODE" \
  -d redirect_uri="https://app.example.com/callback" \
  -d code_verifier="$VERIFIER" \
  -d resource="https://panel.rankshark.io/v1/track"

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "track:read track:run"
}

Keep your key safeCopy Anchor Link

• Server side only. Use keys from your own servers and scripts. Never put a key in a web page, browser code, a mobile app or a public repository: anyone who has it can use your workspace and spend your points.
• In the header, never in a URL. Send the key only as Authorization: Bearer …. A key in a link or query string ends up in logs and browser history.
• HTTPS only. Call https://panel.rankshark.io and keep certificate checks on in your HTTP client.
• Keys, not sign-in cookies. Scripts use a key or an OAuth token. Never copy cookies from a signed-in panel into code.
• One place. Keep the key in an environment variable or a secrets manager, not in code.
• Least access. For an app or AI assistant, prefer OAuth: approve only the scopes it needs, and revoke it on its own when you are done. An assistant that only reads needs only the :read scopes.
• Rotate. Regenerate the key when someone who had it leaves, and from time to time. Open Settings, API & MCP and click Regenerate: the old key stops working at once, so update your scripts with the new one.
• Switch it off. Turning API access off refuses every key and connected app of that product until you turn it back on.