Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation


Copyright (C) 2018-2023 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.


Common/Shared library for Edge APIs.


The intent of edge-common is to simplify the implementation of edge APIs by providing much of the boilerplate code shared among these APIs.


  1. Extend EdgeVerticleHttp and define your API routes by overriding the public Router defineRoutes() method. See some of the unit tests to be inspired, such as EdgeVerticleHttpTest or EdgeVerticleCoreTest.

    From version 1.0.0 to 3.1.0 of edge-common there were two Verticle implementations, EdgeVerticle and EdgeVerticle2. Edge-common version 4.0.0 offers two implementation, EdgeVerticleCore and EdgeVerticleHttp (which happen to be similar to EdgeVerticle2 in earlier versions).

    This provides you with all the basics including configuration, initialization of secure store and token cache, etc.

  2. Use InstitutionalUserHelper for common/shared tasks like parsing API keys, getting OKAPI tokens, etc.

  3. Extend or use OkapiClient directly for making calls into FOLIO.

    For security reasons be restrictive when setting HTTP headers in requests to Okapi. Do not pass request.headers(), instead use MultiMap.caseInsensitiveMultiMap().add(...) with only required headers.

  4. Other bits you may find helpful:

The existing edge APIs: edge-patron, edge-rtac, and edge-orders make extensive use of these features, and serve as examples for how to use edge-common.

Dependency Management

Edge APIs should provide Module Descriptors which define their dependencies (e.g. on backend modules). Registering these module descriptors with OKAPI allows FOLIO's dependency management to be leveraged/extended to the edge APIs. See existing edge APIs for examples.


For now, some level of security is achieved via API Keys. Eventually we may want to implement a more sophisticated security model, e.g. based off of OAuth2, etc.

API Keys

The API Keys used by the edge APIs are a URL safe base64 encoding of the three pieces of information:

  1. Salt - A random string of characters known only to the issuer of the API key, e.g. nZ56F3LeAa
  2. Tenant ID - A FOLIO tenant ID, e.g. diku
  3. Institutional Username - The username of the institutional user for this tenant. This could be the same as the tenant ID, or something else, e.g. diku or dikurtac, etc.

A simple JSON object is created containing these components, which is then base64 encoded, e.g. {"s":"nZ56F3LeAa","t":"diku","u":"diku"}. Note that the field names are abbreviated in the interest of keeping the API keys as short as reasonably possible.

The final API Key looks something like: eyJzIjoiblo1NkYzTGVBYSIsInQiOiJkaWt1IiwidSI6ImRpa3UifQ==

The purpose of the salt is to prevent API Key from being guessed, which would be easy if the tenant ID was known, especially if the Institutional Username was the same as the tenant ID.

API Key Utilities

A utility class has been provided to help with API key generate, parsing, etc. The utility can be use programatically, or via a command line interface. Example CLI usage:

$ mvn package

$ java -jar target/edge-common-api-key-utils.jar
Usage: ApiKeyUtils [options]
 -g                   : generate an API Key (default: false)
 -p VAL               : parse an API Key
 -s (--salt-len) N    : the number of salt characters (default: 10)
 -t (--tenant-id) VAL : the tenant's ID
 -u (--username) VAL  : the tenant's institutional user's username

$ java -jar target/edge-common-api-key-utils.jar -g -s 20 -t diku -u diku

$ java -jar target/edge-common-api-key-utils.jar -p eyJzIjoiQlBhb2ZORm5jSzY0NzdEdWJ4RGgiLCJ0IjoiZGlrdSIsInUiOiJkaWt1In0=
Salt: BPaofNFncK6477DubxDh
Tenant ID: diku
Username: diku

API Key Sources

The API Key can be specified as either:

  1. The apiKey query argument, e.g. https://.../validate?apiKey=eyJzIjoiQlBhb2ZORm5jSzY0NzdEdWJ4RGgiLCJ0IjoiZGlrdSIsInUiOiJkaWt1In0=
  2. The Authorization request header (see note below), e.g. Authorization: apikey eyJzIjoiQlBhb2ZORm5jSzY0NzdEdWJ4RGgiLCJ0IjoiZGlrdSIsInUiOiJkaWt1In0=
  3. As part of the URI path (denoted by :apiKeyPath when defining routes in VertX), e.g. https://.../validate/eyJzIjoiQlBhb2ZORm5jSzY0NzdEdWJ4RGgiLCJ0IjoiZGlrdSIsInUiOiJkaWt1In0=

This behavior is controlled by the api_key_sources system property. The property takes a comma-separated list of sources; valid sources are HEADER, PARAM, and PATH. The order in which the sources are specified determines the order in which that source will be checked for the existance of an API key.

NOTE: There are two ways an API key may be provided by the Authorization header:

  1. Authorization: apikey eyJzIjoiQlBhb2ZORm5jSzY0NzdEdWJ4RGgiLCJ0IjoiZGlrdSIsInUiOiJkaWt1In0= (the auth type 'apikey' is case insensitive)
  2. Authorization: eyJzIjoiQlBhb2ZORm5jSzY0NzdEdWJ4RGgiLCJ0IjoiZGlrdSIsInUiOiJkaWt1In0=

TIP: You can limit the API Key sources used by only listing those you want to check.

Institutional Users

The idea here is that a FOLIO user is created for each tenant for the purposes of edge APIs. The credentials are stored in one of the secure stores and retrieved as needed by the edge API.

The Edge API does not create users, or write credentials. Those need to be provisioned manually or by some other process. The current secure stores expect credentials to be stored in a way that adheres to naming conventions. See the various secure store sections below for specifics.

Currently, it's standard practive to make the institutional username the same as the tenantId, but this is not enforced programatically.

Secure Stores

Three secure stores currently implemented for safe retrieval of encrypted credentials:


Only intended for development purposes. Credentials are defined in plain text in a specified properties file. See src/main/resources/


Retrieves credentials from Amazon Web Services Systems Manager (AWS SSM), more specifically the Parameter Store, where they're stored encrypted using a KMS key. See src.main/resources/

Key: <salt>_<tenantId>_<username>

e.g. Key=ab73kbw90e_diku_diku


Retrieves credentials from a Vault ( This was added as a more generic alternative for those not using AWS. See src/main/resources/

Key: <salt>/<tenantId> Field: <username>

e.g. Key=ab73kbw90e/diku, Field=diku


Configuration information is specified in two forms:

  1. System Properties - General configuration
  2. Properties File - Configuration specific to the desired secure store

System Properties

Property Default Description
port 8081 Server port to listen on
okapi_url required Where to find Okapi (URL)
secure_store Ephemeral Type of secure store to use. Valid: Ephemeral, AwsSsm, Vault
secure_store_props NA Path to a properties file specifying secure store configuration
token_cache_ttl_ms 3600000 How long to cache JWTs, in milliseconds (ms)
null_token_cache_ttl_ms 30000 How long to cache login failure (null JWTs), in milliseconds (ms)
token_cache_capacity 100 Max token cache size
log_level INFO Log4j Log Level
request_timeout_ms 30000 Request Timeout
api_key_sources PARAM,HEADER,PATH Defines the sources (order of precendence) of the API key.

Additional information

There will be a single instance of okapi client per OkapiClientFactory and per tenant, which means that this client should never be closed or else there will be runtime errors. To enforce this behaviour, method close() has been removed from OkapiClient class.

Issue tracker

See project EDGCOMMON at the FOLIO issue tracker.

Other documentation

Other modules are described, with further FOLIO Developer documentation at