Authentication & API Tokens

Rankion authenticates API calls exclusively via Laravel Sanctum bearer tokens. There is no cookie auth, no basic auth, and no API keys without a token. Every token is bound to exactly one user in exactly one team.

Creating a token

Tokens are issued in the web UI — Rankion shows the plaintext token only once, after that only the hashed value is in the DB.

1. Log in at rankion.ai.
2. Open Settings → API Tokens (direct link: /settings/api-tokens).
3. Click "Create new token", give it a meaningful name (e.g. local-dev, n8n-prod, claude-code) and optionally an expiry date.
4. Copy the token immediately into your password manager or your application's .env. Once the dialog closes it is no longer visible.

RANKION_API_TOKEN=ranKion_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Using the token

Every request needs two headers:

Authorization: Bearer <your-token>
Accept: application/json

For POST/PUT/PATCH also Content-Type: application/json.

curl example

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"

# GET — list projects
curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     "$BASE/projects"

# POST — new project
curl -X POST "$BASE/projects" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"name":"My Site","domain":"example.com"}'

Example response

{
  "data": {
    "id": 42,
    "name": "My Site",
    "domain": "example.com",
    "team_id": 7,
    "created_at": "2026-05-01T08:30:00Z"
  }
}

Team scoping

Every Sanctum token is team-scoped. Concretely:

• The token "knows" the user's team at the moment of creation.
• All endpoints filter resources by team_id. If you try to read or mutate a resource from another team, the API responds with 403 Forbidden (no data leaks in the body — existence is not revealed).
• For the image gallery endpoint and a few others cross-team is even answered with 404, so that not even the existence of a foreign ID leaks out.
• If the user is in multiple teams and switches teams, new tokens reference whichever team is currently active. Existing tokens keep their original team scope.

Rotating / revoking tokens

Tokens have no built-in "refresh". Rotation is a two-step process:

1. Create a new token under /settings/api-tokens.
2. Switch your client/job over to the new token.
3. Revoke the old token via the "Delete" button on the same page — from that click on, every request with the old token immediately returns 401 Unauthenticated.

If you suspect a leak: revoke immediately, then issue a new one. The operation is destructive but safe — running async jobs (e.g. an article generation) are not affected, since they run server-side internally.

Best practices

• Never commit to the frontend. Tokens are pure server credentials. In browser code they are exposed — route public API calls through your own backend proxy.
• One token per integration. Separate n8n-prod, vercel-cron, claude-code-local. If one leaks, you only revoke that one without disturbing the others.
• Env vars instead of hardcoding. process.env.RANKION_API_TOKEN / getenv('RANKION_API_TOKEN') — never as a string in the repo.
• Set an expiry date for temporary tokens (e.g. local development, one-off migrations).
• No tokens in logs. Redact the Authorization header in request logging.
• HTTPS only. Rankion does not accept HTTP calls — without TLS the token would be compromised instantly.

Auth-layer error codes

Continue with Credits & Rate Limits.