---
url: https://docs.dataflair.ai/guide/authentication.md
description: >-
  The two authentication modes for the Toplist API, the bearer header, scopes
  and IP allowlisting.
---

# Authentication

The Toplist API supports two independent authentication modes. Both are fully supported, real,
production auth paths. This isn't a "legacy vs. new" situation, it's two tools for two situations.

Whichever mode you use, every authenticated request carries the resulting token the same way:

```
Authorization: Bearer <token>
```

## Which mode should I use?

For a periodic background-sync integration, fetching data on a schedule rather than on the critical
path of a real visitor request, which is the pattern this site's APIs are designed around (see
[Integration model](/dataflair/toplist-api/integration-model)), a **static token** is the simpler fit: no
exchange call, no expiry to manage.

An **HMAC key/secret exchange** is documented too, for integrations whose operational constraints
favor short-lived, auto-expiring credentials in memory over one long-lived static value. That's your
call to make, not a case where one mode is deprecated.

## Static token

DataFlair issues you a static bearer token directly, out of band. Your DataFlair account contact
provides it; there's no self-service endpoint to mint one. Use it directly as the bearer token on
every request, with no exchange call required. It stays valid until revoked or until its own
`expires_at` (if any): treat it as a long-lived secret, stored the way you'd store any API key,
never in a repo or client-side code.

## Key/secret exchange

Exchange a key + secret pair for a short-lived signed bearer token via a dedicated exchange
endpoint. See each API's own reference page for the exact exchange request/response shape, for
example, the Toplist API's [Auth token endpoint](/dataflair/toplist-api/authentication).

## Scopes

Every credential, on either auth mode, carries a list of scopes. Each endpoint you call requires a
specific scope; a credential missing it gets a `403 insufficient_scope` response, not partial or
filtered data. Unless your DataFlair contact has deliberately issued you a narrower credential, this
isn't something you need to actively manage day to day. It's here so a `403` with that error code
is recognizable if it ever comes up.

## IP allowlisting {#ip-allowlisting}

A credential may optionally be restricted to a specific list of source IPs on DataFlair's side. If
yours is, calling from an unlisted IP fails. See [Error handling](/guide/error-handling) for how
this surfaces.