Authentication & API tokens

How the web app authenticates with JWT, how programmatic clients use scoped API tokens, and how to wire each product up securely.

Two ways to authenticate

Rank uses two distinct credential types depending on who is talking to the platform:

• JWT — used by the web app at aleex-rank.ai. When you log in you receive a short-lived access token and a longer-lived refresh token; the refresh token transparently renews the access token. Accounts may enable two-factor authentication (TOTP), which adds a one-time code to the login step. JWTs travel in the Authorization: Bearer <jwt> header.
• API tokens — used by the CLI, the Python SDK, the REST API and CI/CD pipelines. They are long-lived credentials that look like rk_live_... or rk_test_... and travel in the X-API-Key header.

JWTs are for interactive humans in a browser session; API tokens are for automation. Everything outside the web app authenticates with an API token. The two headers are not interchangeable: the Authorization: Bearer header only accepts a JWT, and X-API-Key only accepts an rk_ token.

API tokens

Live vs test

Every request authenticates by sending the token in the X-API-Key header:

X-API-Key: rk_live_xxxxxxxxxxxxxxxx

Create a token

The dashboard is the easiest route, but token management is also fully programmatic: you can list, create, scope and revoke tokens through the API and the SDK. See the Authentication & account API for the /auth/api-tokens endpoints and the SDK’s client.auth.api_tokens resource.

Scoped tokens

By default a token inherits all of your permissions. A scoped token is restricted to a subset, following the principle of least privilege. A scoped token can never have more permissions than the user who created it — only fewer.

You can restrict a token along two independent axes:

• Permissions — by individual permission_ids or by tags that expand to a group of endpoints (for example, the pentest tag). Permission and tag selections are combined.
• Teams — by team_ids, limiting the token to specific team workspaces. A token associated with a team is also counted against that team’s token pool instead of your individual pool.

If a request falls outside the token’s scope, the API responds with 403 Forbidden and an explanatory message — either the endpoint is not in the token’s permission set, or the team is not in its team_ids.

{
  "name": "CI/CD pipeline",
  "tags": ["pentest"],
  "permission_ids": [12, 13],
  "team_ids": [4]
}

Tier limitation

API token limits are set per tier, and the two token pools are independent:

The lowest tier, Casual, cannot create personal API tokens. A Casual user who belongs to a team can still create team tokens as long as the team’s pool has room. See Teams & tiers for how the pools work.

Authenticate each product

rank auth set rk_live_xxxxxxxxxxxxxxxx
rank auth status

import rank

# Reads RANK_API_KEY from the environment
client = rank.Rank()

# Or pass it explicitly
client = rank.Rank(api_key="rk_live_xxxxxxxxxxxxxxxx")

curl https://api.aleex-rank.ai/api/v2/pentests \
  -H "X-API-Key: rk_live_xxxxxxxxxxxxxxxx"

Security best practices

• Use environment variables or a secret manager. Never hard-code tokens or commit them to a repository. The CLI keeps them in ~/.rank-cli/credentials; the SDK reads RANK_API_KEY.
• Scope to least privilege. For automation, create a scoped token limited to the exact permissions and teams the job needs rather than a full-access token.
• Separate environments. Use rk_test_... for development and rk_live_... only where you really mean to act on production.
• Rotate and revoke. Revoke unused or leaked tokens from Settings > API Tokens or via the API. Because tokens are long-lived, treat them like passwords.
• Prefer team tokens for shared work so the credential and its usage are owned by the team, not a single member.