Authenticating to the MangaDex API

While most of the critical features such as finding manga and downloading chapters are open to everyone, many endpoints require authentication.

The client will automatically renew the session and refresh tokens if possible.

Methods that require authentication will check if the client is authenticated. If the client is unauthorized, an Unauthorized will be raised with the method and the relative path taken.

There are two ways to authenticate: via refresh token and via username/password.

Refresh Token

Refresh tokens are the preferred way to authenticate to the API. They do not require the storage of sensitive data and can easily be revoked should there be a need to do so. To use a refresh token, initialize the client with the refresh_token parameter (see Obtaining a Refresh Token to get a refresh token):

client = MangadexClient(refresh_token="my refresh token here")


  • No need to store username/password

  • Can be easily revoked


  • Need to be renewed every so often (currently lasts for one month)


The username and password pair is the common way to log into MangaDex, as they are more memorable than long refresh token strings. They are recommended for one-off client sessions and for local testing/development. There are two ways of entering the username and password: either through the Client initializor or through the login() method.


  • Do not need to be renewed (allows the client to self authenticate without never needing outside intervention such as supplying a new refresh token)


  • Login credentials have to be stored in order to be supplied to the client if the client is used in a script

  • Login information needs to be prompted for if it is not stored

Utilizing Both Refresh Tokens and Username/Password

When a new session token is obtained, the library will also check if the token is valid. If the token is invalid, the client will logout (without calling the logout endpoint) and be set to anonymous mode. If you want to check without fetching a new session token, use ClientUser.fetch() (which is implicitly called by get_session_token()), which will do the same thing.

Initializing Via Constructor

client = MangadexClient(username="your username", password="your password")

Initializing Via Login Method

client = MangadexClient()
await client.login(username="your username", password="your password")

Obtaining a Refresh Token

When you log in via the username and password, a refresh token is generated, which is then used to obtain the session token that is actually used in authentication. The refresh token is available via the MangadexClient.refresh_token attribute.

client = MangadexClient(username="your username", password="your password")
await client.login()