Authentication

Every Ranksy API v1 request is authenticated with an opaque, team-scoped API key sent as a Bearer token. Keys begin with rk_live_ (live mode) or rk_test_ (test mode), and each key resolves to exactly one Ranksy team — you can only read the apps that belong to that team.

Making authenticated requests

Include your key in the Authorization header of every request using the Bearer scheme:

Authorization header

Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Example request

curl https://ranksyapp.com/api/v1/apps/01JN4HKQX0000000000000000/metrics/mrr \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

The only public endpoint that does not require a key is the health check, GET /api/v1/__ping. Every metrics request must be authenticated.

Getting a key

API keys are issued from your team settings inside Ranksy. Sign in, open your team's settings, and create a key — give it a descriptive name and copy it immediately, as the secret is shown only once. Keys are stored opaquely; if you lose one, revoke it and issue a new one.

Keys are bound to the team that created them. There is no per-user token: a key represents the team, and every request made with it is scoped to that team's apps.

Test mode vs live mode

Keys come in two flavours, distinguished by their prefix:

Name
rk_live_
Type
live key
Description
Reads live partner metrics for your team's apps. This is what production integrations use.
Name
rk_test_
Type
test key
Description
A test-mode key for development and sandboxing. Note that partner metrics never contain Shopify test data, so the figures themselves are unaffected by mode.

Scopes

A key carries one or more scopes. The metrics endpoint requires the metrics:read scope; a key granted the wildcard * scope also satisfies it.

Name
metrics:read
Type
required for metrics
Description
Read access to partner metrics. Required by GET /api/v1/apps/{app}/metrics/{metric}.
Name
*
Type
wildcard
Description
Grants all scopes, including metrics:read.

What can go wrong

Authentication and authorization failures are reported through the standard error envelope:

Name
401 — missing / invalid key
Type
authentication_error
Description
The Authorization header is absent or the key is unknown or revoked.
Name
401 — missing_team_scope
Type
authentication_error
Description
The key is valid but is not bound to a team, so no apps can be resolved.
Name
403 — insufficient_permissions
Type
permission_error
Description
The key is valid and team-scoped, but lacks the metrics:read (or *) scope.