Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.7.0] - 2026-06-06

Added

  • Implementations of a new RefreshRepository interface for handling refresh token operations in the AuthenticationService. This includes methods for creating, retrieving, and deleting refresh tokens. Implementations for file-based, in-memory, and database-based refresh token storage are provided.
  • An interface called HTTPClient for the client and session parameters of the RestApiRepository class. This allows for more flexible handling of HTTP requests and responses in the API repository, and allows for customized HTTP clients.

Changed

  • The AuthenticationService class has been updated to use the new RefreshRepository interface for managing refresh tokens. This includes changes to the login, logout, and token refresh methods to utilize the refresh token storage and retrieval functionality provided by the RefreshRepository implementations. This change allows for more flexible management of refresh tokens in the authentication flow and a more modular design.
  • Deprecated the session parameter of the RestApiRepository class in favor of the new client parameter. The client parameter is now the preferred way to handle HTTP requests and responses in the API repository, and allows for more flexible handling of HTTP interactions. The session parameter is still supported for backward compatibility, but it is recommended to switch to using the client parameter for new code and to update existing code to use the client parameter.

Removed

  • The refresh_token_storage, refresh_token_repository_name, refresh_token_storage_file_path, and refresh_token_length configuration options have been removed in favor of the new RefreshRepository implementations. This creates a break in backward compatibility. Following the semantic versioning guidelines, this change should be considered a major change, but since the library is still in development and has not yet reached a stable 1.0 release, this change is included in a minor release. This allows for more flexibility in making changes to the library during the development phase while still following semantic versioning principles.

[0.6.3] - 2026-05-28

Added

  • Added support for Attrs and Pydantic models to the JSONEncoder class. This allows for easier serialization of Attrs and Pydantic models to JSON format.
  • Added additional parameters to the LDAPConnector class to allow for more flexible configuration of LDAP connection and server parameters. This allows for better compatibility with different LDAP servers and use cases.

Changed

  • Updated typing of the ResponseFactory.process to allow for more flexible parameter types.
  • The Accept header is now forwarded to the response-builder function with a accept_header parameter in the API controller template. This allows for better handling of different response formats based on the Accept header sent by the client. This behavior can be used for example to return a different response format than the default JSON format based on the Accept header sent by the client. It can be overruled by using the x-content-type vendor extension to specify a specific content type. Keep in mind that the default response builder function does not use the accept_header parameter, so you will need to implement your own custom response builder function if you want to use this feature. The custom response builder function can be specified in the OpenAPI spec using the x-alpha-custom-response-builder vendor extension and should be imported using the x-alpha-import vendor extension as introduced in version 0.6.1.
  • All specified response types are now being forwarded with a supported_accept_headers parameter to the response-builder function, which can be used to specify a list of supported response formats for the endpoint.

Fixed

  • Applied a fix for the identity variable in the generated API controller code, which was not of the correct type. This caused issues when using the identity variable as a service parameter or when parsing it by the ResponseFactory, as it was not recognized as an Identity object. The fix ensures that the identity variable is of the correct type and can be used properly in several functions.

[0.6.2] - 2026-05-08

Changed

  • FilterOperator class now supports recursive nesting of filter operators. This allows for more complex search queries by combining multiple filter operators together. For example, you can now create a filter operator that combines an AND operator with an OR operator to create a more complex search query.

Fixed

  • When using multiple security schemes in the OpenAPI spec, the generated API code added multiple @inject decorators to the controller functions, which caused issues when running the API. This has been fixed by only adding one @inject decorator to the controller functions, regardless of the number of security schemes defined in the OpenAPI spec.

[0.6.1] - 2026-05-01

Added

  • Added a custom_response_builder function to the OpenAPI python-flask controller template which can be used to build a custom response object. This can be used for example to return a different response format than the default JSON format or to set custom headers in the response. The function can be specified in the OpenAPI spec using the x-alpha-custom-response-builder vendor extension and should be imported using the x-alpha-import vendor extension.

Changed

  • Use a default value of ["*"] for the CORS origins if not configured in the container. This allows for easier development and testing of the generated API without having to configure CORS origins in the container.
  • Using default response headers when not configured in the container. This ensures secure defaults for the response headers and allows for easier development and testing of the generated API without having to configure response headers in the container.

Fixed

  • When refreshing an authentication token using the refresh token, the Identity object was not merged with the user and group information from the database, which caused issues when using group-based permissions. This has been fixed by merging the Identity object with the user and group information from the database after refreshing the token. This was only an issue when the refresh_identity_on_refresh parameter of the AuthenticationService was set to True.
  • When using the x-alpha-custom-function vendor extension in the OpenAPI spec, it whas not possible to use quotes in the value of the vendor extension because it was not properly escaped in the generated code. This has been fixed by properly escaping the value of the x-alpha-custom-function vendor extension in the generated code.

[0.6.0] - 2026-04-28

Added

  • to_dict method to Group model for easier serialization of Group objects.
  • to_dict method to User model for easier serialization of User objects.
  • Compatibility for Sequence and Mapping types to the GenericTypeFactory class to allow for more flexible type handling in the factories.
  • OpenAPI python-flask controller template:
    • Support for file uploads by using the x-alpha-filelist parameter in the requestBody of the OpenAPI spec.
    • Support for debug logging of the request parameters and body when the logging level is set to DEBUG.
    • Support for debug logging of the response body when the logging level is set to DEBUG and x-alpha-debug-response parameter is set to true in the OpenAPI spec.
    • Support for a custom function by using the x-alpha-custom-function parameter. Only when not using the x-alpha-service-name parameter.
    • Support for using x-alpha-cookie-support when not returning data (204 status code). In this case, the response object will be created with the create_response_object function which supports setting and deleting cookies in the response. This can be used for example for a logout endpoint which needs to delete the authentication cookies.
    • Extended exception handling to also catch 405, 501, 502, 503 and 504 status codes and return a proper response with the correct status code and error message.
  • Additional unit and integration tests for the API templates and the generated code.
  • Support for python 3.14 by patching an issue with the ast library. This allows the generated API code to be compatible with python 3.14.
  • JWTFactory class now has a lifetime_seconds parameter which can be used to set the lifetime of the generated JWT tokens. This allows for better control over the token expiration and can be useful in different use cases (e.g. short-lived tokens for sensitive operations, long-lived tokens for less sensitive operations). The parameter takes precedence over the lifetime_hours parameter if both are provided.
  • Documentation for all relevant classes and functions in the codebase.

Changed

  • controller template only adds inject decorator if there are actually dependencies to inject.
  • Removed dependencies for the generated API library. The dependencies are managed separately by the alpha library by specifying the flask extra for the python-flask generator.
  • logout method of the AuthenticationService class now also deletes the refresh token cookie if it exists.
  • The tests run for each supported python version with tox instead of only one version. This allows for better testing of the compatibility of the library with different python versions.
  • JWTFactory now defaults to a token lifetime of 900 seconds (15 minutes) instead of 12 hours. This is a more secure default value for the token lifetime, as it reduces the window of opportunity for an attacker to use a stolen token.

Fixed

  • OpenAPI python-flask model template created models which were unable to be instantiated without passing all parameters as arguments. This has been fixed by renaming the class variables to have a leading underscore.
  • update_user & update_group methods in the UserLifecycleManagement service were not correctly updating the user and group objects in the database. The update logic has been fixed and now properly updates the user and group objects in the database.

[0.5.1] - 2026-04-16

Added

  • Added the Headers class to handle HTTP request headers, including support for authorization tokens, refresh tokens, and API keys.
  • Added support for extracting tokens from cookies in the Headers class in the API controller template.
  • Added support for setting and deleting cookies in the API response handling when using the x-alpha-cookie-support vendor extension.
  • Added support for defining additional service method parameters when using the x-alpha-service-additional-parameters vendor extension. This can be used to pass additional parameters to the service methods, such as the Identity object or authentication tokens.
  • Added a UserLifecycleManagement service for managing user lifecycle operations such as creating, updating, and deleting users and groups. This service uses a SqlRepository for database interactions.
  • Added a Role model to the domain models, which can be used to define roles for users.

Fixed

  • The get_payload method of the JWTFactory class did not have an option to disable validation of the token, which is necessary in some cases (e.g. when you want to extract the payload without validating the token). This has been fixed by adding a validate parameter to the method which is False by default.

[0.5.0] - 2026-04-02

Implements a repository for REST API's, refresh-token based authentication flows (with cookie support), introduces group-based permission merging alongside new unit/integration tests and dependencies.

Added

  • Add an ApiRepository interface, a RestApiRepository implementation for domain model lifecycle management and a RestApiUnitOfWork for API session management.
  • Add support for Cookies to the create_response_object function, which is used by the generated API code to set or delete cookies in the response.
  • Add support for Cookies to the AuthenticationService class, so it can generate cookies after login or remove them on logout.
  • Add support for Refresh tokens and cookies to the AuthenticationService class.
  • Add option to AuthenticationService to authenticate with a statically configured user. This option can be used in development and testing environments.
  • Add option to AuthenticationService to merge permissions from database Group objects with the Identity.
  • Add refresh token creation/storage/refresh flow to AuthenticationService (file/memory/database backends) and group merging support.
  • Add centralized HTTP response handling in RestApiRepository plus tests (including an httpx-backed client test).
  • Introduce new domain/model utilities (Group, Token enhancements, generate_secret) and expand integration test fixtures.

Changed

  • Updated the response handling of the RestApiRepository for better error handling. A specific exception will now be raised for each 4xx or 5xx status code.

[0.4.0] - 2026-02-23

Added

  • Added PasswordFactory class which can be used for password hashing. It contains methods for hashing and verification of a password. By default it uses the argon2.PasswordHasher class with a salt length of 16, but this can by overruled during initialization.
  • Added DatabaseProvider class which is an implementation of IdentityProvider. This provider uses a database to store user information and credentials, and provides methods for authenticating users, retrieving user information, and changing passwords.

Fixed

  • Added FLASK_ENV=production to Dockerfile mustache template so the API runs in the proper mode.

Changed

  • Loosened up the version dependency of the dependency-injector library and excluded version 4.48.3 because of a PydanticImportError. https://github.com/ets-labs/python-dependency-injector/issues/942.

[0.3.3] - 2026-01-28

Added

  • Added support for having a pyproject.toml file that only contains metadata in the [tool.poetry] section instead of a [project] section.

[0.3.2] - 2026-01-27

Fixed

  • Fixed a bug that alpha cannot be imported when the ldap extra is not installed. The classes that depend on the ldap3 library will now not be imported in init.py modules when ldap3 is not installed.

Changed

  • When using the alpha api gen command the presents of the openapi-generator-cli package is checked first.

[0.3.1] - 2026-01-20

Fixed

  • Fixed a bug in the AuthenticationService when the merge_with_database_users parameter is True. Identity object was not updated correctly by the User object from the database.

[0.3.0] - 2026-01-19

Added

  • Adds OIDCConnector and KeyCloakOIDCConnector classes for OAuth2/OIDC protocol operations
  • Implements OIDCProvider and KeyCloakProvider classes for identity management via OIDC

Changed

  • Refactors LDAP provider to add configurable connection parameters and improve error handling
  • Updates TLS configuration in LDAP connector from deprecated PROTOCOL_TLSv1_2 to PROTOCOL_TLS_CLIENT

[0.2.6] - 2026-01-16

Fixed

  • controller template for python-flask api generator contains trailing comma's for authorization variables which is incorrect syntax.

Changed

  • Improved logic for parsing ldap/AD groups by the Identify class

[0.2.5] - 2026-01-15

Added

  • ADProvider class for AD identity providers. The class extends the LDAPProvider class and overrides the default parameter values.
  • AD_SEARCH_ATTRIBUTES constant which are used by default by the ADProvider class.
  • Imports of all classes and functions at root module level.

Fixed

  • Unable to merge attributes of a User object to an Identity object due to a wrong parameter name.

[0.2.4] - 2026-01-13

Fixed

  • Previously, the base image in the Dockerfile.mustache template was hardcoded, which made it impossible to use a base image other than the default base image python:3.13. Now, it is possible to pass a different base image as a build argument

[0.2.3] - 2026-01-12

Fixed

  • missing imports in __main__.mustache template.

[0.2.2] - 2026-01-12

Fixed

  • When the api cli is being used from a folder which does not contain a src folder the guessed input options contain None. The _guess_current_package_name function now looks for a pyproject.toml file from which the package name is fetched. If the file is not present, it scans the subfolders for a python project. The current folder name is used as a fallback

[0.2.1] - 2026-01-12

Fixed

  • Shell scripts for api code generation are not packaged.

[0.2.0] - 2026-01-11

Minor release with added features. An identity provider for LDAP and a cli interface for generating and running API code by using mustache templates.

Added

  • Interfaces for identity providers
  • JWTFactory
  • JWTProvider mixin
  • LDAPConnector
  • LDAPProvider
  • AuthenticationService
  • ApiGenerateHandler
  • ApiRunHandler

[0.1.0] - 2026-01-10 [YANKED]

Initial release

Added

  • adapters
  • domain.models
  • factories
  • factories.models
  • infra.databases
  • infra.models
  • interfaces
  • repositories
  • repositories.models
  • utils
  • encoder.py
  • exceptions.py