Guides

Authentication

The 18 endpoints on this site need no credentials. There are no API keys to request and no Authorization header to send.

Public endpoints#

Every documented endpoint returns only what Rankd already shows to someone who is not signed in:

Profiles only of people who chose to be discoverable.
Ratings, reviews and lists only when they are public. Private and followers-only content is never returned, and is never counted in community numbers.
Nothing personal: fields such as community.myRating are always null, and the feed is the community’s, not anyone’s own (meta.personalized is false).

If you do send an Authorization header to a public endpoint and the token is not valid, it is ignored and the request is answered as a public one.

Everything else#

The rest of the Rankd API (someone’s own ratings, following, notifications, writing reviews and so on) belongs to Rankd’s own apps. It needs a Rankd session, which is issued only when someone signs in to a Rankd app. Called without one, it answers:

401 Unauthorized

{
  "error": {
    "code": "unauthenticated",
    "message": "A Rankd session or operator token is required."
  }
}

Rankd does not offer API keys, OAuth or any other way for a third-party app to act for a Rankd user today. Do not ask people for their Rankd password or copy a session token out of a Rankd app: sessions are short-lived, tied to Rankd’s apps, and using them elsewhere is not supported.

Calling from a browser#

The API does not send CORS headers, so a web page on another site cannot read its responses. Call it from your server, a serverless function or a native app, and pass the results to your page. Images at /v1/assets/… are the exception: they allow any origin, so you can use avatarUrl directly in an <img> tag.

The Try it panels on this site work because this site calls the API from its own server, with no credentials, and only for the documented endpoints.

Keeping it safe#

Always use https://.
Treat everything the API returns as untrusted text: escape display names, bios, list titles and review bodies before putting them in HTML.
Cache what you can. Public content changes slowly, and caching keeps you well under the rate limit.