API Keys

API keys are user-scoped, long-lived tokens that can be used to authenticate requests to the REST API. While originally developed to support third-party integrations, they are a useful tool for any user that wants to interact with Stump programmatically or develop their own integrations.

Generating an API Key

To generate an API key:

1. Navigate to the app settings (/settings/app)
2. Click the API keys tab (/settings/app/api-keys)
3. Click the Generate API key button
4. Give your key a name, assign it permissions, optionally declare an expiration date, and click Create key

Once a key is generated, you will be presented with the full key. This key will not be shown again, so be sure to copy it to a secure location. If you lose the key, you will need to generate a new one.

Using an API Key

You can authorize a request to your Stump instance by including the key value in the Authorization header of your requests. The header should look like this:

Authorization: Bearer <your_api_key>

If you’re using the Stump SDK, you can set it directly when you create the SDK instance:

import { Api } from '@stump/sdk'
 
// Create a new SDK instance, passing in your API key
const sdk = new Api({
	baseURL: 'https://my-stump.cloud',
	authMethod: 'api-key',
	apiKey: '<your_api_key>',
})
 
// Now you can make requests
const library = await sdk.library.get({ name: ['Ebooks'] })

This will automatically include the key in the request headers for you.

Special API Key Routes

There are instances where you can embed an API key in the URL directly. This is primiarily only done for instances 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

Permissions

API keys use the same permissions as user accounts. When creating a key, you have the option of:

• Inheriting the permissions of the user that created the key
• Assigning specific permissions to the key

It is generally recommended to assign only the permissions that are necessary for the key to function. This is a security best practice, as it limits the potential damage that could be done if the key were to be compromised.

Considerations

The permissions available to managed user accounts grant access to functionality beyond what is “base level” for a user. For example, any user may fetch a book from a library (assuming age restrictions, library exclusions, etc, are not in play). Therefore, any API key will have the ability to fetch a book from a library, even if the key was created with 0 explicit permissions. This is because a key is associated with a user, and while you can filter out permissions the user has for the key, you cannot filter out permissions the user implicitly has.

If there is demand for it, these permissions may be made configurable in the future. Please open a feature request on the repository if you would like to see this functionality.

Revoking an API Key

To revoke an API key, you can just delete it entirely. This will immediately invalidate the key, and it will no longer be usable for authentication.

Other important notes relating to API key revocation / invalidation:

• A user with a locked account will not be able to use their API key(s)
• A user who is soft-deleted will not be able to use their API key(s)
• A user who created an API key but has their access to the API keys feature revoked (feature:api_keys) will not be able to use their API key(s)