Personal Access Tokens

A Personal Access Token (PAT) is a long-lived credential that lets tools outside the dashboard act as you: the RankNest REST API, the CLI, and the MCP server all authenticate with the same token. Tokens start with rnk_live_ and can never see clients or data you can't see in the dashboard.

Where to find it

Open Account Settings, go to the Integrations tab, and click Developer API. The Personal Access Tokens panel sits below the connection guides.

How to create a token

1. Click Create token in the Personal Access Tokens panel.
2. Enter a Name that tells you where the token will be used, for example "Claude Desktop" or "Reporting script".
3. Choose a Scope (see below). For almost every use, pick User.
4. Click Create token. A green banner confirms the token was created and shows the full token once.
5. Click the copy button, store the token in a password manager or secrets store, then click Done.

After the banner is dismissed, the token list only ever shows the first few characters of each token, along with its name, scope, when it was last used, and when it was created.

Token scopes

• User: the token sees only your own clients, experiments, link maps, and tasks, exactly as the dashboard does. This is the right choice for the CLI, MCP connections, and any script or integration you build.
• Admin: full platform access, intended for RankNest platform administrators. An Admin-scope token only works while your account holds an admin role. Agencies should not need this scope.

Using your token with the REST API

The Developer API area's REST API tab shows a ready-to-copy example. Send the token as a bearer token in the Authorization header:

curl "https://www.ranknest.io/api/v1/clients" \
  -H "Authorization: Bearer rnk_live_XXXXXXXXXXXXXXXX"

• Base URL: https://www.ranknest.io/api/v1. Always use the www subdomain. Requests to the bare domain are redirected in a way that strips the authorization header.
• Available resources include /clients, /experiments, /link-maps, /tasks, /campaigns, /content-batches, /seo-variables, and /functions/*.
• All requests inherit your subscription limits. The API, MCP, and CLI share the same caps as the dashboard. See Pricing for your plan's limits.

Revoking a token

1. Find the token in the Personal Access Tokens list.
2. Click the trash icon on its row.
3. Confirm the prompt. Any client using this token stops working immediately.

Revoked tokens stay in the list with a revoked badge so you keep a record of what existed. Revoke a token any time you suspect it leaked, when you retire the tool that used it, or when a teammate who knew it leaves. Create a fresh one if you still need access.

Tips

• Create one token per tool or script rather than sharing a single token everywhere. When something needs to be cut off, you can revoke just that token.
• The used timestamp in the token list updates as tokens are used. A token that shows "never" after weeks is a good candidate for revoking.
• Name tokens after the place they live ("CI server", "Claude Code on my laptop"), not after what they do. Six months later that's the detail you'll want.

Troubleshooting

"Admin access required" when opening Developer API. Your account doesn't have an admin role. Ask your agency owner to grant it. See Team Members.

API requests return 401 Unauthorized. The token was revoked, mistyped, or sent to the bare domain instead of www.ranknest.io. Check the token list for a revoked badge and confirm your base URL includes www.

A script that worked yesterday stopped working. Check whether the token was revoked, and whether the account that created it still has the access the script relies on. Tokens never grant more than the owning account can do.

Related

• MCP Server Setup
• CLI
• Team Members