API

The core API which a Stump server exposes is a GraphQL API. There are some RESTful endpoints, as well, but these are generally reserved for integrations and features which require it (e.g., fetching thumbnails). The API is backed by a few different authentication methods.

The API is constantly being developed, and while it is generally stable at this point it is still subject to change.

Authentication

Sessions

Stump uses server-side sessions to authenticate users. These sessions are stored in the database, and are automatically cleaned up within 60 seconds of expiring. You can change the expiry cleanup check interval by setting the SESSION_EXPIRY_CLEANUP_INTERVAL environment variable. See the configuration guide for more information.

Basic Authentication

Stump supports Basic Authentication in order to properly support OPDS clients. Authenticating using this method will not create a server-side session. It is only intended for OPDS client authentication.

JWT Tokens

Short-lived JWT access tokens are available for API access, aimed at better enabling third-party applications and extensions to interact with Stump. There are also longer-lived refresh tokens that can be used to obtain new access tokens, but cannot be used to authenticate requests.

JWT Generation

The generation of JWTs is fairly standard. Each type of token (access and refresh) is encoded with its own unique secret, and the payload is signed using the HS256 algorithm. The important bit to highlight here is that Stump will generate two secrets for you on boot and store them in the database. If you need to rotate these secrets for any reason, you can do so by deleting them from the database. They will be automatically regenerated on the next boot, but note that all existing tokens will effectively be invalidated.

API Keys

You can generated user-scoped API keys to authenticate requests to the REST API. These keys are stored in the database and can be revoked at any time. API keys are not subject to the same expiry as sessions, and are intended for long-term use.

Special API Key Routes

There are instances where you can embed an API key in the URL directly. This will only be available for features/integrations where passing the key in the header is otherwise impossible. At the time of writing, there are two such routes:

• /koreader/{api_key}/* - Used for the KoReader sync integration. See here for more information
• /opds/{api_key}/v1.2/* - An optional clone of the OPDS integration API for clients which don't support auth headers

For more information on API keys, see the API keys guide.

GraphQL Playground

The playground should be enabled by default when running the server in debug mode, or if the enable_playground config variable is set to true, and will be available at http(s)://your-server(:10801)/api/graphql.

If you're new to GraphQL, I would recommend giving the GraphQL documentation a quick read, and then trying out the playground.

Disabling GraphQL Playground

If you don't want to expose the GraphQL Playground, you can disable it by setting the ENABLE_GRAPHQL_PLAYGROUND environment variable to false. See the configuration guide for more information.