New JWT authentication

[advplyr]

Overview

Audiobookshelf has replaced its token-based authentication system with JWT (JSON Web Token) authentication using refresh tokens. The new system includes database-backed session management and a separate auth method using configurable API keys.

The initial rollout (v2.26.0) includes no breaking changes to allow for the mobile apps to migrate and any 3rd party apps to migrate.

Key Changes

JWT Authentication System

• Access Tokens: Short-lived tokens used for requests
• Refresh Tokens: Long-lived tokens used to create new access tokens
• Session Management: Database-backed session tracking with automatic cleanup
• Token Rotation: Refresh tokens are rotated on each use

API Key System

• Standalone API Keys: Admin users can generate configurable API keys for scripts and automation
• User Association: API keys act on behalf of selected users, maintaining existing permission structure
• Configurable Expiration: Optional expiration dates for API keys

Security Enhancements

• Rate Limiting: Rate limiter (per IP address) applied to authentication endpoints
• Automatic Token Refresh: Token renewal handled by client-side interceptors when access tokens expire
• Session Invalidation: Database-based session tracking with token revocation on logout
• Environment Configuration: Token expiration times, rate limiter settings, and JWT secret configurable via environment variables

Migration Notes

• New auth is added in v2.26.0 and contains no breaking changes
• The old authentication system will continue to function and be removed from the server no earlier than September 30, 2025 to allow 3rd party apps time to update
• In v2.26.0 Users will be required to re-authenticate on first use
• All new sessions use the JWT system
• API keys provide a solution for automation scripts
• Default JWT expirations will change as the new auth system matures (access token shorter, refresh longer)

Authentication Flows

JWT Authentication Flow

1. JWT User Login

   • User submits credentials via /login endpoint
   • Server validates credentials and generates access + refresh tokens
   • Access token returned in response body
   • Refresh token set as HTTP-only cookie

2. JWT Refresh Process

   • When access token expires, server returns 401 Unauthorized on the next request
   • Client automatically calls /auth/refresh endpoint
   • Server validates refresh token from cookie
   • New access and refresh tokens generated and returned
   • Original failed request retried with new access token

3. JWT Logout Process

   • Client calls /logout endpoint
   • Server invalidates refresh token in database
   • Refresh token cookie cleared

See API endpoints

API Key Authentication Flow

1. API Key Creation

   • Admin user creates API key via /api/api-keys endpoint (or web client)
   • Specifies name, associated user, expiration (optional), and active status
   • Server creates a record in the apiKeys table
   • Server generates JWT-based API key with embedded UUID of the db record

2. API Key Usage

   • Client includes API key in Authorization header: Bearer <api_key>
   • Server validates API key and loads associated user
   • Request proceeds with user's permissions and account type

3. API Key Management

   • Admin users can view, update, and delete API keys
   • API keys can be deactivated without deletion
   • Expired API keys are automatically deactivated

Configuration

Environment Variables

• ACCESS_TOKEN_EXPIRY: Access token expiration in seconds (initial default: 43200 = 12 hours)
• REFRESH_TOKEN_EXPIRY: Refresh token expiration in seconds (initial default: 604800 = 7 days)
• RATE_LIMIT_AUTH_WINDOW: Rate limiting window in milliseconds (default: 600000 = 10 minutes)
• RATE_LIMIT_AUTH_MAX: Maximum auth attempts per window (default: 40) (use 0 to disable rate limiter)

Warning: Do not change the secret on an existing server until the next mobile app release or until the 3rd party app you are using has migrated. This will make the old tokens unusable so that only migrated apps can authenticate with your server.

• JWT_SECRET_KEY: Custom JWT signing secret (auto-generated if not provided)

[advplyr]

JWT Auth Endpoints

POST /login

Authenticates user credentials and returns access token.

Headers:

• x-return-tokens (optional): When set to true, returns refresh token in response body for mobile clients

Request Body:

{
  "username": "string",
  "password": "string"
}

Response (not full):

{
  "user": {
    "id": "uuid",
    "token": "old_token",
    "refreshToken": "refresh_token", // Only if x-return-tokens header is true
    "accessToken": "new_jwt"
    ...
  },
  ...
}

The only change is the refreshToken and accessToken. The old token remains in the response in order to keep backwards compatibility

Mobile Usage: For mobile applications that cannot use HTTP-only cookies, include the x-return-tokens: true header to receive the refresh token in the response body for secure storage. Then for refreshing and logout pass the refresh token in x-refresh-token header.

POST /auth/refresh

Refreshes expired access token using refresh token.

Headers:

• x-refresh-token (optional): For mobile clients that don't use cookies

Response:

Same response as /login. If x-refresh-token is passed then refresh token is returned in response.

POST /logout

Invalidates current session and clears refresh token.

Headers:

• x-refresh-token (optional): For mobile clients that don't use cookies

Response:

{
  "redirect_url": "string" // For OIDC logout
}

[fabrikant]

Hi!
I really like this project and it's great that not only the interface is developing, but the backend. Maybe the question is not for this topic, but do you have any plans to optimize the API?
I think the huge responses of unused data that the API returns are a problem. On my instance, when adding a book to a playlist, 4000kB of json data is downloaded from the server. This action takes ~10 seconds. And we get unjustified network overhead. This is true for most API endpoints.

[advplyr]

Yes, we will be improving the API. That is extremely slow for 4000kB. We will definitely improve the API and reduce the response sizes where we can but it may also be worth investigating why your server/network is struggling with 4000kB

[julianhille]

need advisory on swag / nginx / fail2ban filter in front.

Since the update fail2ban pretty regularly kills me and the web client. as there are way more 401s.

Possible solutions:

• raise some expiry times
• exclude audiobookshelf from fail2ban or specific filters
• add some ignoreregex to fail2ban

what is your point on that?

[advplyr]

The default expiration of the access token is 12 hours so there shouldn't be way more 401s.
I've never used fail2ban so I'm not sure about that. Returning a 401 unauthorized and refreshing an expired token should be standard so maybe they have some docs on that

[julianhille]

Im opening a Lot of Tabs when working with mappings of broken series or authors. Maybe thats a Problem. I dont think its an issue with fail2ban as this just looks at/scans log Files. And the log clearly Staates 401s with follows up redirects.

Depends on where the Frontend stores the auth/refresh tokens.

[100nandoo]

i'm working on 3rd party android app for audiobookshelf, just to clarify regarding this new JWT token implementation.
With this new token system, for api calls lets say library, library items or sync session apis, the new access token is pass as header on Bearer accessToken and also need to pass refresh_token on Cookie?

[100nandoo]

Got it, thanks.

Also thanks so much for everything you're doing with Audiobookshelf. I can only imagine the countless hours and effort you've poured into both the server and the app — it's truly impressive. You've built something really special, and I just wanted to say I genuinely appreciate it. I actually developed a third-party Android app for Audiobookshelf myself, so I’ve seen firsthand how much care and detail has gone into the project.

[advplyr]

Thank you! It is a joy to work on and I hope the third-party app is for you also

[rpgdev]

@advplyr I second what @100nandoo said. I recently started looking into the source code to see how you guys were handling auth. Aab is easily the best-organized Express services I’ve seen, kudos to you and everyone who’s worked on it over the years. Unfortunately, seeing Express services in the wild at work has kind of given me PTSD, though admittedly I’m not a JS dev, just do it on the side from time to time. Did you follow a particular philosophy when deciding how to organize the code, or was it DIY? It's ofc similar to what mvc promotes but that seems to be hard for many js backend devs to stick to it smh.

[advplyr]

Before I started using NodeJS I used Laravel, an opinionated MVC PHP framework. It is the structure I was familiar with and still makes the most sense to me. It has gotten more refined over the years by necessity.
One of the problems is that the Express endpoints were not written in a way that we can easily set up auto-generated API docs. That will be one of the refactors coming down the road.

[rpgdev]

Makes sense. Time, and backend.js, has only made laravel look better and better imho.

[GrakovNe]

Could you please explain what the correct way if access and refresh tokens are both expired? Shall I redirect the user on Login page?

[H2OKing89]

What I’m trying to say is that this level of security feels a bit excessive for a media app like ABS. Users generally don’t expect to be forced to re-login in native apps, especially if they haven’t used it for a few weeks. This behavior makes sense for banking or enterprise tools, but for a personal audiobook app it can feel frustrating and unnecessary.

Maybe a better approach would be to allow native apps to create long-lived API keys (not with admin privileges) or to make the refresh token effectively permanent for app usage. This would improve the UX without significantly compromising security, especially if the token is scoped and revocable.

security should never be taken lightly, period. Also, ABS has the ability to delete data so I want high security.

Trust me, I get it—nobody wants to have to re-login to their audiobook app after a week of binging something else on Netflix. But here’s the kicker: ABS isn’t just a glorified player, it’s also got admin-level powers under the hood. If your account gets hijacked, it’s not just your playback settings at risk; someone could nuke your whole library or mess with your metadata. It’s like handing the keys to your house to anyone who gets past a “meh” lock.

Is it a bit much compared to Spotify? Maybe. But Spotify doesn’t let you mass-delete your files, right?

That said, I do like the idea of long-lived, scoped API keys—if they’re clearly limited and easily revocable. Maybe there’s a way to make things less annoying without giving up that safety net. But until I see a way to guarantee that someone can’t just walk in and wipe out years’ worth of audiobooks because of a stale session, I’m gonna side with “mild annoyance > digital disaster.”

Security is like seat belts—everyone grumbles about buckling up, but nobody argues after the crash.

[advplyr]

It is a little more effort for third party developers to implement, but this way users that want the security of expiring tokens can have it. Users that don't want that security can set the refresh token expiration to a very large number, effectively permanent.

Several users pointed out that the old authentication system's permanent tokens are a security vulnerability. I think that is true for just about any software. It was a necessary update in my opinion.

Technically third party apps can create permanent API keys if an admin user logs in. API keys shouldn't be used for 3rd party apps though.

[GrakovNe]

I'm totally fine with supporting the current implementation from a developer's perspective — I've already done most of the work. I'm more concerned about the user experience. If users are logged out just because they haven't used the app for a week, it might become frustrating. Especially for a native app, people expect to just open it and start listening without extra steps.

[advplyr]

The refresh token default will get extended after some time. Possibly to 30 days, not sure yet.
But like I said the server owner can set it to whatever they want which is much better than not being to set it at all. A big net positive to user experience.

[Vito0912]

I am not sure if that was already decided, but there was a suggestion to make the refresh token valid for 30 days instead of 7 after some time. This would help find bugs by having a shorter lifespan for now. (see above)
Because In my opinion, 7 days is also a bit short for this.

The main security concern was that the sent token was valid forever. That is fixed now, as it is valid for an even shorter time. So by sniffing or sending a request including a token no harm is done really anymore after at max 12 hrs iirc

[chancez]

For those of us using OIDC for authentication where our IDP is already providing authentication, how does the introduction of JWT based authentication impact us?

[advplyr]

Nothing has changed with how you will login. The difference is that once you authenticate the server will respond with the new access token that will be used for requests. You shouldn't notice any difference unless you don't open the mobile/web app for 7 days then you will have to re-login (that will be extended to 30 days most likely).

[GrakovNe]

30 days is welcome!

[benfishbus]

I have been using Pocket-ID to authenticate to abs - both web and iOS app. Today the iOS app stopped working. I can still log in normally on web, including from my phone. But the iOS app says the server is not connected, and when I hit the Connect button and hit the server name, it says "Failed to authorize (No refresh token available)". Running 2.27.0 server and 0.10.0 app

[benfishbus]

That worked. Going forward are you saying the app will prompt for reauthentication without having to remove and re-add the server?

[Vito0912]

It still will. This is a bug.
I didn't work at the mobile apps at all, so idk why this happens (But I also don't understand why we don't revert for the time being as this renders the official app unuseable for anyone using OIDC)

I have set the values to 90 days respectively and hope that at very latest this will be fixed with the new release schedule

[ovizii]

Can I ask for some clarification please?

I only started using ABS v2.29.0 about 2-3 days ago and set it up with OIDC. After 2 days of using it, I also got hit with the error: “failed to authorize no refresh token available” and had to remove and re-add the server.

It was suggested to raise the values of ACCESS_TOKEN_EXPIRY and REFRESH_TOKEN_EXPIRY, right? Does that not simply prolong the time before we are hit with the same error again?
Also, how does that work in conjunction with the “Session duration” value of Pocket ID?

[Vito0912]

The new update should have fix the issue. Please try updating.
If you still experiencing the issue, please comment on the old one

[ovizii]

The new update should have fix the issue. Please try updating. If you still experiencing the issue, please comment on the old one

Since I am on the latest ABS server version, I am assuming you are referring to the ABS android app, so I updated from v0.10.0-beta to v0.10.1-beta hoping that was what you meant.