Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Copyright (C) 2016-2022 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.


This module is responsible for filtering all proxy traffic and checking for a valid token. In addition, it is responsible for retrieving the permissions for a given user and making decisions regarding access based on user permissions and defined requirements for a given path. It provides a token creation endpoint that privileged modules (such as Authentication) may make use of.


System requirements

  • Java 11

  • Apache Maven 3.3.x or higher

Quick start

mvn install
java -jar target/mod-authtoken-far.jar


In addition to acting as a filter, the module exposes a few endpoints that are accessible as part as the regular Okapi ecosystem. These endpoints are as follows:

  • /token - This endpoint signs and returns an access token (JWT). It requires the permission auth.signtoken, which must be defined as a module permission to be used. It accepts a POST of a JSON object, with a field called payload that contains the claims of the token. The token is returned inside of a JSON object (response code 201), containing a field called token that has the token as a value.

  • /refreshtoken - This endpoint signs and returns a refresh token (JWE). It requires the permission auth.signrefreshtoken, which must be defined as a module permission. It accepts a POST of a JSON object, with required fields of userId and sub. The token is returned inside of a JSON object (response code 201), contained in a field called refreshToken.

  • /refresh - This endpoint takes a valid refresh token and returns a new access token. It accepts a POST of a JSON object, with required field refreshToken that contains the refresh token. It returns a new access token inside of a JSON object (response code 201), contained in a field called token.

The expiration time is hard-coded:

  • 10 minutes for access tokens
  • 24 hours for refresh tokens

MODAT-65 will make it configurable.

Command Line Options/System Properties

mod-authtoken supports a number of command line options as system properties, set by passing -D<>=<value> to the jar when loading.

  • jwt.signing.key - A passphrase to use as a signing key. If not set a random key is generated on each module restart invalidating all previously issued tokens. For clustering all instances of mod-authtoken must be configured to use the same key.
  • perm.lookup.timeout - Timeout for lookups to mod-permissions in seconds. Defaults to 10.
  • user.cache.seconds - Time to cache user permissions in seconds. Defaults to 60.
  • user.cache.purge.seconds - Time before a user is purged from the permissions cache in seconds. Defaults to 43200 (12 hours).
  • sys.perm.cache.seconds - Time that system permissions are cached in seconds. Defaults to 259200 (3 days).
  • sys.perm.cache.purge.seconds - Time before system permissions are purged from the permissions cache. Defaults to 43200 (12 hours).
  • log.level - Module log level.
  • port - Port the module will listen on. Defaults to 8081.
  • cache.permissions - Boolean controlling the permissions cache. Defaults to true.

Custom Headers

Passing a value of "true" to the Authtoken-Refresh-Cache header for any request will inform mod-authtoken to delete the permissions cache for that userid and to request fresh permissions, regardless of cache age.

Additional information

Refresh Tokens Designs and Decisions

Other modules.

Other FOLIO Developer documentation is at

Issue tracker

See project MODAT at the FOLIO issue tracker.


See the ModuleDescriptor for the interfaces that this module requires and provides, the permissions, and the additional module metadata.

API descriptions:

Generated API documentation.

Code analysis

SonarQube analysis.

Download and configuration

The built artifacts for this module are available. See configuration for repository access, and the Docker image.


Module for filtering requests based on JWT tokens







No packages published