rodauth-api_keys 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad5a7297a151e1a68b312507d366ab66f522a20281e79c03f1de348910efb449
+  data.tar.gz: f855c8e5d9460b3e8a1a872ea8498a4442407f0893224f485d5408d2b4a65c22
+SHA512:
+  metadata.gz: 0d859b69ae9c618bfed8158ac04c1a47190726d90fd8a34c4677b0e0e752bed5724a617f16c35a0fa8b1d3c4713789ef7b29234a58fb529b6938a0980f410fdc
+  data.tar.gz: 4fdf738230d2cfd3716b933abd85b55d9a44f842bef2d21b576149a119b58e5ce019e83c7c42f368932f31fa367f0d5525095effc11deba5113de2965e04248b

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-10-03)
+
+First version.
+
+- Add the `api_keys` feature for Rodauth.
+- Add the `create-api-key`, `api-keys`, and `revoke-api-key` routes, with HTML templates and JSON responses.
+- Authenticate a request with an API key in the `Authorization` header. The request does not use the cookie session.
+- Keep only the key digest and the key hint in the database. Show the full API key one time only.
+- Add scopes, an optional expiration date, and a limit of active API keys for each account.
+- Record the last use of each API key.
+- Send the expiration time of the API key in the `api-key-expiration` response header.
+- Revoke all API keys of an account when the account closes. Optionally revoke them when the password changes.
+- Add internal request methods: `create_api_key`, `api_keys`, and `revoke_api_key`.
+- Register an `api_keys` association for rodauth-model.
+- Support the `json`, `jwt`, `active_sessions`, `single_session`, `two_factor_base`, `audit_logging`, and `internal_request` features.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Pavel Dušánek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,378 @@
+# rodauth-api_keys
+
+The `api_keys` feature for [Rodauth](https://github.com/jeremyevans/rodauth) lets an account create, list, and revoke API keys.
+A client sends an API key in the `Authorization` header. Rodauth then authenticates the request as the account that owns the API key.
+
+```
+Authorization: Bearer rak_Qb4JPgNpNhcsdekspshofQVvGUcpchLRstT6HAu7EQS
+```
+
+## Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Database migration](#database-migration)
+- [Configuration](#configuration)
+- [Authenticate API requests](#authenticate-api-requests)
+- [Management pages](#management-pages)
+- [JSON API](#json-api)
+- [Internal requests](#internal-requests)
+- [Model association](#model-association)
+- [Configuration reference](#configuration-reference)
+- [Security](#security)
+- [Development](#development)
+
+## Features
+
+- An API key has a configurable prefix, for example `myapp_`. Secret scanners, such as GitHub secret scanning, can find a leaked API key by its prefix.
+- The database keeps only an HMAC digest and a short hint of each API key. The account sees the full API key one time only.
+- An API key request does not use the cookie session and does not set a cookie.
+- An API key can have scopes and an expiration date.
+- The account can revoke an API key. Rodauth keeps the row and sets `revoked_at`.
+- Each account can have a maximum number of active API keys.
+- HTML pages and JSON responses for the management routes.
+- Internal request methods for create, list, and revoke.
+- The feature works with the `json`, `jwt`, `active_sessions`, `single_session`, `two_factor_base`, `close_account`, `change_password`, `reset_password`, `audit_logging`, and `internal_request` features.
+
+The feature uses only Rodauth and the Ruby standard library.
+
+## Installation
+
+Add the gem to the `Gemfile` of the application:
+
+```ruby
+gem "rodauth-api_keys"
+```
+
+Requirements:
+
+- Ruby 3.3 or later
+- Rodauth 2.48 or later
+
+## Database migration
+
+Add a table for the API keys. This example uses Sequel:
+
+```ruby
+Sequel.migration do
+  change do
+    create_table(:account_api_keys) do
+      primary_key :id, type: :Bignum
+      foreign_key :account_id, :accounts, type: :Bignum, null: false
+      String :name, null: false
+      String :digest, null: false, unique: true
+      String :hint, null: false
+      String :scopes
+      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :last_use
+      DateTime :expires_at
+      DateTime :revoked_at
+      index [:account_id, :revoked_at]
+    end
+  end
+end
+```
+
+If the `accounts` table uses UUID primary keys, change the type of `account_id` to `:uuid`.
+You can change the table name and each column name with the configuration methods (see [Configuration reference](#configuration-reference)).
+
+## Configuration
+
+Enable the feature and set `hmac_secret`. The feature calculates the key digest with `hmac_secret`.
+
+```ruby
+plugin :rodauth do
+  enable :login, :logout, :api_keys
+  hmac_secret ENV.fetch("RODAUTH_HMAC_SECRET")
+
+  api_key_prefix "myapp"
+  api_key_scopes %w[projects:read projects:write]
+  api_key_max_lifetime 86400 * 365
+end
+```
+
+Feature order: enable `api_keys` after `jwt`, `active_sessions`, `single_session`, `two_factor_base`, and the features that use `two_factor_base` (`otp`, `sms_codes`, `webauthn`, `recovery_codes`).
+If the order is wrong, Rodauth raises `Rodauth::ConfigurationError` when the application starts.
+
+```ruby
+enable :login, :logout, :jwt, :otp, :recovery_codes, :api_keys
+```
+
+## Authenticate API requests
+
+When a request has an `Authorization: Bearer <prefix>_...` header, the feature finds the API key in the database.
+If the API key is active and the account is open, these methods work as in a cookie session:
+
+- `rodauth.require_authentication`, `rodauth.require_account`
+- `rodauth.logged_in?`, `rodauth.session_value`, `rodauth.account_from_session`
+
+If the API key is not valid, the response is `401 Unauthorized` with `WWW-Authenticate: Bearer realm="api", error="invalid_token"`.
+The feature does not use the cookie session as a fallback.
+
+Example Roda routes:
+
+```ruby
+route do |r|
+  r.rodauth
+
+  r.on "api" do
+    # Accept only API keys.
+    rodauth.require_api_key_authentication
+
+    r.get "projects" do
+      rodauth.require_api_key_scope("projects:read")
+      # rodauth.session_value is the ID of the account that owns the API key.
+      # ...
+    end
+
+    r.post "projects" do
+      rodauth.require_api_key_scope("projects:write")
+      # ...
+    end
+  end
+end
+```
+
+Example client request:
+
+```sh
+curl -H "Authorization: Bearer myapp_Qb4JPgNpNhcsdekspshofQVvGUcpchLRstT6HAu7EQS" https://example.com/api/projects
+```
+
+Methods for the application:
+
+| Method | Description |
+|---|---|
+| `rodauth.api_key_authenticated?` | True if an API key authenticated the request. |
+| `rodauth.require_api_key_authentication` | Send `401` if no valid API key authenticated the request. |
+| `rodauth.current_api_key_id` | The ID of the API key of the request, or `nil`. |
+| `rodauth.current_api_key_scopes` | The scopes of the API key of the request, or `nil`. |
+| `rodauth.api_key_scope?(scope)` | True if the request has the scope. A cookie session has all scopes. |
+| `rodauth.require_api_key_scope(*scopes)` | Require authentication. Then send `403` with `error="insufficient_scope"` if the API key does not have all the scopes. A cookie session has all scopes. |
+
+### Two-factor authentication
+
+An API key counts as full authentication. The account used all its authentication factors when it created the API key.
+
+### Last use
+
+The feature records the time of use in `last_use`. It updates the column at most one time in `api_key_last_use_update_interval` seconds (default 60).
+Set the value to `nil` to update the column on each request.
+
+### Expiration header
+
+When an API key has an expiration time, each response to a request with that API key contains it in the `api-key-expiration` header.
+The value is an HTTP date:
+
+```
+api-key-expiration: Thu, 31 Dec 2026 22:59:59 GMT
+```
+
+A client can use the header to replace the API key before it expires. An API key without an expiration time gets no header.
+No standard header exists for this value. GitHub uses a similar header, `GitHub-Authentication-Token-Expiration`.
+The name does not start with `X-`, because [RFC 6648](https://www.rfc-editor.org/rfc/rfc6648) recommends against that prefix.
+
+```ruby
+api_key_expiration_header "myapp-key-expiration" # Change the header name.
+api_key_expiration_header nil                   # Remove the header.
+api_key_expiration_header_value do |expires_at| # Change the format of the value.
+  expires_at.utc.iso8601
+end
+```
+
+## Management pages
+
+| Route | Description |
+|---|---|
+| `/api-keys` | The list of API keys of the account: name, hint, scopes, created, last use, expiration date, and status. |
+| `/create-api-key` | A form to create an API key. The next page shows the full API key one time. |
+| `/revoke-api-key` | A form to revoke an active API key. |
+
+Rules for these routes:
+
+- The account must be logged in.
+- A request that an API key authenticated gets `403`. An API key cannot create or revoke API keys. See [Security](#security).
+- If the account has a password, the form asks for it.
+- The page that shows the new API key sends `Cache-Control: no-store`.
+
+The expiration date field accepts a date (`2026-12-31`) or a full ISO 8601 time (`2026-12-31T12:00:00Z`).
+A date without a time is the last second of that day (23:59:59), in the time zone of the application.
+The database calculates `expires_at` with its own clock, as Rodauth does for its deadlines.
+
+To change a page, put a template with the same name in the views directory of the application:
+`api-keys.str`, `create-api-key.str`, `api-key-created.str`, or `revoke-api-key.str`.
+
+## JSON API
+
+With the `json` feature, the management routes accept and return JSON. All requests use `POST`.
+
+Create an API key:
+
+```sh
+curl -X POST https://example.com/create-api-key \
+  -H "Content-Type: application/json" -H "Authorization: <JWT>" \
+  -d '{"api_key_name": "CI server", "password": "...", "api_key_scopes": ["projects:read"], "api_key_expires_at": "2026-12-31"}'
+```
+
+```json
+{
+  "api_key": "myapp_Qb4JPgNpNhcsdekspshofQVvGUcpchLRstT6HAu7EQS",
+  "id": 1,
+  "name": "CI server",
+  "hint": "myapp_Qb4J",
+  "scopes": ["projects:read"],
+  "created_at": "2026-10-02T12:00:00+00:00",
+  "last_use": null,
+  "expires_at": "2026-12-31T23:59:59+00:00",
+  "revoked_at": null,
+  "status": "active",
+  "success": "Your API key is ready. Copy it now. You cannot see it again."
+}
+```
+
+- `POST /api-keys` returns `{"api_keys": [...]}`. Each item has the same fields, but no `api_key`.
+- `POST /revoke-api-key` with `{"api_key_id": 1, "password": "..."}` returns `{"success": "The API key is revoked"}`.
+- An error returns `{"error": "...", "field-error": ["<parameter>", "<message>"]}`.
+
+The `api_key_scopes` parameter can also be a string with scopes separated by spaces.
+
+## Internal requests
+
+With the `internal_request` feature:
+
+```ruby
+result = App.rodauth.create_api_key(account_login: "user@example.com", api_key_name: "CI server", api_key_scopes: ["projects:read"])
+result[:api_key] # => "myapp_..."
+
+App.rodauth.api_keys(account_login: "user@example.com")
+# => [{id: 1, name: "CI server", hint: "myapp_Qb4J", scopes: ["projects:read"], status: :active, ...}]
+
+App.rodauth.revoke_api_key(account_login: "user@example.com", api_key_id: result[:id])
+```
+
+Internal requests do not ask for the password. An error raises `Rodauth::InternalRequestError`.
+
+## Model association
+
+With [rodauth-model](https://github.com/janko/rodauth-model), the account model gets an `api_keys` association.
+Require `rodauth/model` before you enable `api_keys`. The feature registers the association only when `Rodauth::Model` is defined.
+
+```ruby
+class Account < Sequel::Model
+  include Rodauth::Model(RodauthApp.rodauth)
+end
+
+account.api_keys # => [#<Account::ApiKey @values={id: 1, name: "CI server", ...}>]
+account.api_keys_dataset.where(revoked_at: nil)
+```
+
+The rows contain the key digest and the key hint. They do not contain the API key.
+When you remove the account with `destroy`, the model also removes its API key rows.
+
+## Configuration reference
+
+### Values
+
+| Method | Default | Description |
+|---|---|---|
+| `api_key_prefix` | `"rak"` | The prefix of each API key. Letters and digits, with single underscores between them. |
+| `api_key_secret_length` | `43` | The number of random letters and digits after the prefix (approximately 256 bits). |
+| `api_key_hint_length` | `4` | The number of secret characters in the hint. |
+| `api_key_realm` | `"api"` | The realm in the `WWW-Authenticate` header. |
+| `api_key_authorization_regexp` | `/\ABearer\s+(<prefix>_[A-Za-z0-9]+)\s*\z/` | Finds the API key in the `Authorization` header. The first capture group must contain the API key. |
+| `api_keys_limit` | `10` | The maximum number of active API keys for each account. `nil` removes the limit. |
+| `api_key_name_max_length` | `100` | The maximum length of the name. |
+| `api_key_scopes` | `[]` | The permitted scope names. If the list is empty, the feature does not use scopes. |
+| `api_key_max_lifetime` | `nil` | The maximum lifetime in seconds. A value makes the expiration date necessary. |
+| `api_key_last_use_update_interval` | `60` | The minimum number of seconds between two updates of `last_use`. |
+| `api_key_expiration_header` | `"api-key-expiration"` | The response header with the expiration time of the API key. `nil` removes the header. |
+| `revoke_api_keys_on_password_change?` | `false` | Revoke all API keys after a password change or a password reset. |
+| `api_keys_table` | `:account_api_keys` | The table name. |
+| `api_keys_*_column` | see migration | One method for each column: `id`, `account_id`, `name`, `digest`, `hint`, `scopes`, `created_at`, `last_use`, `expires_at`, `revoked_at`. |
+| `api_key_name_param`, `api_key_expires_at_param`, `api_key_scopes_param`, `api_key_id_param` | `"api_key_name"`, ... | Parameter names. |
+| `api_keys_route`, `create_api_key_route`, `revoke_api_key_route` | `"api-keys"`, ... | Route names. |
+| `insufficient_api_key_scope_error_status` | `403` | The status for a missing scope. |
+| `api_key_management_not_permitted_error_status` | `403` | The status for a request to a Rodauth route with an API key. |
+
+To accept the `Token` scheme too:
+
+```ruby
+api_key_authorization_regexp(/\A(?:Bearer|Token)\s+(myapp_[A-Za-z0-9]+)\s*\z/)
+```
+
+### Messages and labels
+
+You can change each text with its configuration method, for example `invalid_api_key_message "API key not valid"`.
+The texts:
+
+- Messages: `invalid_api_key_message`, `api_key_required_message`, `insufficient_api_key_scope_message`, `api_key_management_not_permitted_message`, `invalid_api_key_name_message`, `invalid_api_key_expires_at_message`, `api_key_expires_at_required_message`, `api_key_expires_at_past_message`, `api_key_expires_at_too_late_message`, `invalid_api_key_scopes_message`, `api_key_scopes_required_message`, `api_keys_limit_message`, `invalid_api_key_id_message`, `no_active_api_keys_message`, `api_keys_empty_message`.
+- Flash messages: `create_api_key_notice_flash`, `create_api_key_error_flash`, `revoke_api_key_notice_flash`, `revoke_api_key_error_flash`.
+- Labels and buttons: the `*_label`, `*_link_text`, `*_button`, and `*_page_title` methods.
+
+### Hooks
+
+`before_api_keys_route`, `before_create_api_key_route`, `before_create_api_key`, `after_create_api_key`, `before_revoke_api_key_route`, `before_revoke_api_key`, `after_revoke_api_key`.
+
+With the `audit_logging` feature, Rodauth logs the `create_api_key` and `revoke_api_key` actions.
+
+### Methods that you can override
+
+`generate_api_key`, `api_key_digest`, `api_key_digests`, `api_key_hint`, `api_key_from_request`, `api_key_insert_hash`, `create_api_key`, `revoke_api_key`, `revoke_all_api_keys`, `account_api_keys`, `valid_api_key_name?`, `valid_api_key_scopes?`, `parse_api_key_expires_at`, `update_api_key_last_use`, `api_key_expiration_header_value`, `api_key_created_response`, `api_key_authenticated?`, `api_key_scope?`, `require_api_key_authentication`, `require_api_key_scope`.
+
+To add a column to each new row, override `api_key_insert_hash`:
+
+```ruby
+api_key_insert_hash do |*args|
+  super(*args).merge(created_ip: request.ip)
+end
+```
+
+## Security
+
+- The database keeps the HMAC-SHA256 digest of the API key, not the API key. A copy of the database does not give the API keys without `hmac_secret`.
+- During a rotation of `hmac_secret`, set `hmac_old_secret`. The feature accepts the old digest and writes the new digest at the next use of the API key.
+- The feature does not write the API key to logs or to error messages.
+- An unverified account cannot use API keys. This is also true in the grace period of `verify_account_grace_period`.
+- A closed account cannot use its API keys. `close_account` revokes them. If `close_account` calls `delete_account`, the feature removes the API key rows first.
+- With the `jwt` feature, a response to an API key request does not contain a JWT. Such a JWT would authenticate the account without the API key.
+- An API key cannot use the Rodauth routes. For example, it cannot change the login, set a remember cookie, or create API keys. The response is `403`.
+  The feature prepends a check to `before_rodauth`. A `before_rodauth` block in your configuration does not remove the check.
+
+### Remove old rows
+
+The feature does not remove revoked or expired rows. To remove rows that are older than 90 days, use a command like this one:
+
+```ruby
+DB.extension :date_arithmetic
+cutoff = Sequel.date_sub(Sequel::CURRENT_TIMESTAMP, days: 90)
+DB[:account_api_keys].where { (revoked_at < cutoff) | (expires_at < cutoff) }.delete
+```
+
+## Development
+
+After you clone the repository, run `bin/setup` to install the dependencies.
+
+- Run the tests and the linter: `bundle exec rake`
+- Run the tests only: `bundle exec rake test`
+- Run the linter only: `bundle exec rake standard`
+- Start a console: `bin/console`
+
+To release a new version:
+
+1. Change the version number in `rodauth-api_keys.gemspec`.
+2. Add the version and the date to `CHANGELOG.md`.
+3. Commit the change and push it to `main`.
+4. On GitHub, start the "Release" workflow (`.github/workflows/release.yml`) on `main`.
+
+The workflow runs the tests and the linter. Then it runs `bundle exec rake release` with the [Release Gem](https://github.com/rubygems/release-gem) action.
+This command makes a git tag for the version, pushes the tag, and pushes the `.gem` file to [rubygems.org](https://rubygems.org).
+If the tag exists, the command does not make it again.
+The workflow uses [trusted publishing](https://guides.rubygems.org/trusted-publishing/). It does not need an API key of rubygems.org.
+
+## Contributing
+
+Send bug reports and pull requests on GitHub at https://github.com/dush/rodauth-api_keys.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rodauth/features/api_keys.rb

@@ -0,0 +1,699 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Rodauth
+  # Rodauth calls before_rodauth at the start of each route.
+  # A before_rodauth block in the configuration replaces the method of a feature.
+  # Thus the api_keys feature prepends this module to the Rodauth class. The block cannot remove the check.
+  module ApiKeysRouteCheck
+    private
+
+    def before_rodauth
+      require_api_key_management_session
+      super
+    end
+  end
+
+  Feature.define(:api_keys, :ApiKeys) do
+    depends :require_hmac_secret
+
+    # Page to create an API key.
+    notice_flash "Your API key is ready. Copy it now. You cannot see it again.", "create_api_key"
+    error_flash "Unable to create the API key", "create_api_key"
+    loaded_templates %w[api-keys create-api-key api-key-created revoke-api-key password-field]
+    view "create-api-key", "Create API Key", "create_api_key"
+    view "api-key-created", "API Key Created", "api_key_created"
+    additional_form_tags "create_api_key"
+    button "Create API Key", "create_api_key"
+    before "create_api_key"
+    after "create_api_key"
+
+    translatable_method :api_key_label, "API key"
+    translatable_method :api_key_name_label, "Name"
+    translatable_method :api_key_expires_at_label, "Expiration date"
+    translatable_method :api_key_scopes_label, "Scopes"
+    translatable_method :invalid_api_key_name_message, "invalid name"
+    translatable_method :invalid_api_key_expires_at_message, "invalid expiration date"
+    translatable_method :api_key_expires_at_required_message, "expiration date is necessary"
+    translatable_method :api_key_expires_at_past_message, "expiration date must be in the future"
+    translatable_method :api_key_expires_at_too_late_message, "expiration date is too late"
+    translatable_method :invalid_api_key_scopes_message, "invalid scope"
+    translatable_method :api_key_scopes_required_message, "select one or more scopes"
+    translatable_method :api_keys_limit_message, "maximum number of active API keys"
+    translatable_method :api_key_management_not_permitted_message, "an API key cannot use this route"
+    auth_value_method :api_key_management_not_permitted_error_status, 403
+
+    # Page with the list of API keys.
+    view "api-keys", "API Keys", "api_keys"
+    translatable_method :api_key_created_at_label, "Created"
+    translatable_method :api_key_last_use_label, "Last use"
+    translatable_method :api_key_status_label, "Status"
+    translatable_method :api_key_active_label, "Active"
+    translatable_method :api_key_expired_label, "Expired"
+    translatable_method :api_key_revoked_label, "Revoked"
+    translatable_method :api_key_never_label, "Never"
+    translatable_method :api_keys_empty_message, "There are no API keys."
+    translatable_method :create_api_key_link_text, "Create API Key"
+    translatable_method :revoke_api_key_link_text, "Revoke API Key"
+
+    # Page to revoke an API key.
+    notice_flash "The API key is revoked", "revoke_api_key"
+    error_flash "Unable to revoke the API key", "revoke_api_key"
+    view "revoke-api-key", "Revoke API Key", "revoke_api_key"
+    additional_form_tags "revoke_api_key"
+    button "Revoke API Key", "revoke_api_key"
+    before "revoke_api_key"
+    after "revoke_api_key"
+    redirect(:revoke_api_key) { api_keys_path }
+    response "revoke_api_key"
+    translatable_method :invalid_api_key_id_message, "select an active API key"
+    translatable_method :no_active_api_keys_message, "There are no active API keys."
+
+    # Format of an API key: "<api_key_prefix>_<secret>".
+    auth_value_method :api_key_prefix, "rak"
+    auth_value_method :api_key_secret_length, 43
+    auth_value_method :api_key_hint_length, 4
+    auth_value_method :api_key_realm, "api"
+
+    # Database table and columns.
+    auth_value_method :api_keys_table, :account_api_keys
+    auth_value_method :api_keys_id_column, :id
+    auth_value_method :api_keys_account_id_column, :account_id
+    auth_value_method :api_keys_name_column, :name
+    auth_value_method :api_keys_digest_column, :digest
+    auth_value_method :api_keys_hint_column, :hint
+    auth_value_method :api_keys_scopes_column, :scopes
+    auth_value_method :api_keys_created_at_column, :created_at
+    auth_value_method :api_keys_last_use_column, :last_use
+    auth_value_method :api_keys_expires_at_column, :expires_at
+    auth_value_method :api_keys_revoked_at_column, :revoked_at
+
+    # Limits and policies.
+    auth_value_method :api_keys_limit, 10
+    auth_value_method :api_key_name_max_length, 100
+    auth_value_method :api_key_scopes, [].freeze
+    auth_value_method :api_key_max_lifetime, nil
+    auth_value_method :api_key_last_use_update_interval, 60
+    # A response to an API key request contains the expiration time of the API key in this header. nil removes the header.
+    auth_value_method :api_key_expiration_header, "api-key-expiration"
+    auth_value_method :revoke_api_keys_on_password_change?, false
+
+    # Request parameters.
+    auth_value_method :api_key_name_param, "api_key_name"
+    auth_value_method :api_key_expires_at_param, "api_key_expires_at"
+    auth_value_method :api_key_scopes_param, "api_key_scopes"
+    auth_value_method :api_key_id_param, "api_key_id"
+
+    # Responses for API key authentication.
+    session_key :api_key_id_session_key, :api_key_id
+    translatable_method :invalid_api_key_message, "invalid API key"
+    translatable_method :api_key_required_message, "API key required"
+    translatable_method :insufficient_api_key_scope_message, "API key does not have the necessary scope"
+    auth_value_method :insufficient_api_key_scope_error_status, 403
+
+    auth_value_methods :api_key_authorization_regexp
+
+    internal_request_method :create_api_key
+    internal_request_method :api_keys
+    internal_request_method :revoke_api_key
+
+    auth_methods(
+      :account_api_keys,
+      :revoke_all_api_keys,
+      :revoke_api_key,
+      :api_key_created_response,
+      :parse_api_key_expires_at,
+      :valid_api_key_name?,
+      :valid_api_key_scopes?,
+      :api_key_authenticated?,
+      :api_key_digest,
+      :api_key_digests,
+      :api_key_from_request,
+      :api_key_hint,
+      :api_key_insert_hash,
+      :api_key_scope?,
+      :create_api_key,
+      :generate_api_key,
+      :require_api_key_authentication,
+      :require_api_key_scope,
+      :update_api_key_last_use,
+      :api_key_expiration_header_value
+    )
+
+    uses_instance_variables(:@created_api_key_id, :@created_api_key, :@session, :@api_key_row)
+
+    # The ID of the row that the last call to create_api_key added.
+    attr_reader :created_api_key_id
+
+    # The API key that the create-api-key route added in this request. The created page shows it.
+    attr_reader :created_api_key
+
+    route(:api_keys) do |r|
+      require_account
+      before_api_keys_route
+      _return_from_internal_request(account_api_keys) if internal_request?
+
+      if respond_to?(:use_json?) && use_json?
+        json_response["api_keys"] = account_api_keys.map { |api_key| api_key_json(api_key) }
+      end
+
+      r.get do
+        api_keys_view
+      end
+
+      r.post do
+        api_keys_view
+      end
+    end
+
+    route(:revoke_api_key) do |r|
+      require_account
+      before_revoke_api_key_route
+
+      r.get do
+        revoke_api_key_view
+      end
+
+      r.post do
+        catch_error do
+          unless (id = param_or_nil(api_key_id_param))
+            throw_error_reason(:invalid_api_key_id, invalid_field_error_status, api_key_id_param, invalid_api_key_id_message)
+          end
+
+          if modifications_require_password? && !password_match?(param(password_param))
+            throw_error_reason(:invalid_password, invalid_password_error_status, password_param, invalid_password_message)
+          end
+
+          transaction do
+            before_revoke_api_key
+            unless revoke_api_key(id)
+              throw_error_reason(:invalid_api_key_id, invalid_field_error_status, api_key_id_param, invalid_api_key_id_message)
+            end
+            after_revoke_api_key
+          end
+
+          revoke_api_key_response
+        end
+
+        set_error_flash revoke_api_key_error_flash
+        revoke_api_key_view
+      end
+    end
+
+    route(:create_api_key) do |r|
+      require_account
+      before_create_api_key_route
+
+      r.get do
+        create_api_key_view
+      end
+
+      r.post do
+        catch_error do
+          if modifications_require_password? && !password_match?(param(password_param))
+            throw_error_reason(:invalid_password, invalid_password_error_status, password_param, invalid_password_message)
+          end
+
+          name = api_key_name_param_value
+          scopes = api_key_scopes_param_value
+          expires_in = api_key_expires_in_param_value
+
+          transaction do
+            before_create_api_key
+            if api_keys_limit && active_api_keys_ds.count >= api_keys_limit
+              throw_error_reason(:api_keys_limit, invalid_field_error_status, api_key_name_param, api_keys_limit_message)
+            end
+            @created_api_key = create_api_key(name, scopes: scopes, expires_in: expires_in)
+            after_create_api_key
+          end
+
+          api_key_created_response
+        end
+
+        set_error_flash create_api_key_error_flash
+        create_api_key_view
+      end
+    end
+
+    # The first capture group must contain the API key.
+    def api_key_authorization_regexp
+      /\ABearer\s+(#{Regexp.escape(api_key_prefix)}_[A-Za-z0-9]+)\s*\z/
+    end
+
+    def post_configure
+      super
+
+      unless api_key_prefix.is_a?(String) && api_key_prefix.match?(/\A[A-Za-z0-9]+(?:_[A-Za-z0-9]+)*\z/)
+        raise ConfigurationError, "api_key_prefix must contain only letters, digits, and single underscores between them: #{api_key_prefix.inspect}"
+      end
+
+      # This feature overrides methods of these features. Thus it must come before them in the method lookup.
+      ancestors = self.class.ancestors
+      [:two_factor_base, :jwt, :active_sessions, :single_session].each do |feature_name|
+        next unless (feature = FEATURES[feature_name]) && ancestors.include?(feature)
+        if ancestors.index(feature) < ancestors.index(FEATURES[:api_keys])
+          raise ConfigurationError, "enable :api_keys after :#{feature_name} and the features that use it"
+        end
+      end
+
+      # An API key must not use the Rodauth routes, for example to change the login or to set a remember cookie.
+      self.class.prepend(ApiKeysRouteCheck) unless self.class < ApiKeysRouteCheck
+
+      api_key_scopes.each do |scope|
+        unless scope.is_a?(String) && scope.match?(/\A[!#-\[\]-~]+\z/)
+          raise ConfigurationError, "api_key_scopes must contain only strings of printable ASCII characters without spaces, quotes, or backslashes: #{scope.inspect}"
+        end
+      end
+    end
+
+    # When the request contains an API key, return a session hash for this request only.
+    # Rodauth does not write this hash to the session cookie.
+    # When the API key is not valid, send a 401 response. Do not use the cookie session.
+    def session
+      return @session if @session
+      return super unless (api_key = api_key_from_request)
+
+      @session = api_key_session(api_key)
+    end
+
+    # Return the API key from the Authorization header, or nil.
+    def api_key_from_request
+      (value = request.env["HTTP_AUTHORIZATION"]) && value[api_key_authorization_regexp, 1]
+    end
+
+    # Return true if an API key authenticated the request.
+    def api_key_authenticated?
+      session
+      !@api_key_row.nil?
+    end
+
+    # Return the ID of the API key that authenticated the request, or nil.
+    def current_api_key_id
+      @api_key_row[api_keys_id_column] if api_key_authenticated?
+    end
+
+    # Return the scopes of the API key that authenticated the request, or nil.
+    def current_api_key_scopes
+      @api_key_row[api_keys_scopes_column].to_s.split(" ") if api_key_authenticated?
+    end
+
+    # Send a 401 response if no valid API key authenticated the request.
+    def require_api_key_authentication
+      return if api_key_authenticated?
+
+      set_response_error_reason_status(:api_key_required, login_required_error_status)
+      set_response_header("www-authenticate", "Bearer realm=\"#{api_key_realm}\"")
+      return_api_key_error_response(api_key_required_message)
+    end
+
+    # Return true if the request has permission for the scope.
+    # A request that the cookie session authenticated has all scopes.
+    def api_key_scope?(scope)
+      if api_key_authenticated?
+        current_api_key_scopes.include?(scope.to_s)
+      else
+        !!authenticated?
+      end
+    end
+
+    # Require authentication. Then send a 403 response if the API key does not have all the scopes.
+    def require_api_key_scope(*scopes)
+      require_authentication
+      return if scopes.all? { |scope| api_key_scope?(scope) }
+
+      set_response_error_reason_status(:insufficient_api_key_scope, insufficient_api_key_scope_error_status)
+      set_response_header("www-authenticate", "Bearer realm=\"#{api_key_realm}\", error=\"insufficient_scope\", scope=\"#{scopes.join(" ")}\"")
+      return_api_key_error_response(insufficient_api_key_scope_message)
+    end
+
+    # The account used all its authentication factors when it created the API key.
+    def two_factor_authenticated?
+      api_key_authenticated? || super
+    end
+
+    # A request that an API key authenticated has no session ID and no single session key.
+    # The active_sessions and single_session features must not end such a request.
+    def currently_active_session?
+      api_key_authenticated? || super
+    end
+
+    # Return all digests that can match the API key. With hmac_old_secret, there are two digests.
+    def api_key_digests(api_key)
+      compute_hmacs(api_key)
+    end
+
+    # Return the value of the expiration header: an HTTP date, for example "Thu, 31 Dec 2026 12:00:00 GMT".
+    def api_key_expiration_header_value(expires_at)
+      expires_at.httpdate
+    end
+
+    # Record the time of use. Skip the update if the last update is more recent than api_key_last_use_update_interval.
+    def update_api_key_last_use
+      ds = api_keys_table_ds.where(api_keys_id_column => @api_key_row[api_keys_id_column])
+      if (interval = api_key_last_use_update_interval)
+        last_use = Sequel[api_keys_last_use_column]
+        ds = ds.where(Sequel.|({last_use => nil}, last_use < Sequel.date_sub(Sequel::CURRENT_TIMESTAMP, seconds: interval)))
+      end
+      ds.update(api_keys_last_use_column => Sequel::CURRENT_TIMESTAMP)
+    end
+
+    # Return true if the name is not empty and not too long.
+    def valid_api_key_name?(name)
+      !name.empty? && name.length <= api_key_name_max_length
+    end
+
+    # Return true if api_key_scopes contains each scope.
+    def valid_api_key_scopes?(scopes)
+      scopes.all? { |scope| scope.is_a?(String) && api_key_scopes.include?(scope) }
+    end
+
+    # Return the expiration time for the value of the form field, or nil if the value is not valid.
+    # A date without a time ("2026-12-31") is the last second of that day in the time zone of the application.
+    # A full ISO 8601 time ("2026-12-31T12:00:00Z") is also valid.
+    def parse_api_key_expires_at(value)
+      if value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        date = Date.iso8601(value)
+        Time.new(date.year, date.month, date.day, 23, 59, 59)
+      else
+        Time.iso8601(value)
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    # Return the API keys of the account, the newest first. Each item is a hash with these keys:
+    # :id, :name, :hint, :scopes (array), :created_at, :last_use, :expires_at, :revoked_at, and :status.
+    # The status is :active, :expired, or :revoked. The database calculates it with its own clock.
+    def account_api_keys
+      api_key_items(api_keys_ds)
+    end
+
+    # Revoke the active API key of the account with this ID. Return true if the API key was active.
+    def revoke_api_key(id)
+      return false unless (id = convert_token_id(id))
+
+      active_api_keys_ds.where(api_keys_id_column => id).update(api_keys_revoked_at_column => Sequel::CURRENT_TIMESTAMP) == 1
+    end
+
+    # Revoke all active API keys of the account. Return the number of revoked API keys.
+    def revoke_all_api_keys
+      active_api_keys_ds.update(api_keys_revoked_at_column => Sequel::CURRENT_TIMESTAMP)
+    end
+
+    # Rodauth calls this method after a password change, a password reset, and other changes to the account.
+    def clear_tokens(reason)
+      super
+      if revoke_api_keys_on_password_change? && [:change_password, :reset_password].include?(reason)
+        revoke_all_api_keys
+      end
+    end
+
+    # The jwt feature reads each Authorization header that does not start with Basic or Digest.
+    # Do not let it read an API key.
+    def jwt_token
+      return if api_key_from_request
+
+      super
+    end
+
+    # Show the new API key one time. Tell the browser and proxies not to keep a copy of the page.
+    def api_key_created_response
+      set_response_header("cache-control", "no-store")
+      set_notice_now_flash create_api_key_notice_flash
+
+      item = api_key_items(api_keys_ds.where(api_keys_id_column => created_api_key_id)).first
+      _return_from_internal_request(item.merge(api_key: created_api_key)) if internal_request?
+
+      if respond_to?(:use_json?) && use_json?
+        json_response.merge!(api_key_json(item), "api_key" => created_api_key)
+        return_json_response
+      end
+
+      return_response(api_key_created_view)
+    end
+
+    # Return a new API key: the prefix, an underscore, and a random secret.
+    # The secret contains only letters and digits.
+    def generate_api_key
+      "#{api_key_prefix}_#{SecureRandom.alphanumeric(api_key_secret_length)}"
+    end
+
+    # Return the value that the database keeps in place of the API key.
+    def api_key_digest(api_key)
+      compute_hmac(api_key)
+    end
+
+    # Return the start of the API key: the prefix, the underscore, and the first characters of the secret.
+    # The list of API keys shows this value.
+    def api_key_hint(api_key)
+      api_key[0, api_key_prefix.length + 1 + api_key_hint_length]
+    end
+
+    # Add an API key for the account. Return the API key.
+    # The database keeps only the key digest and the key hint.
+    # expires_in is the lifetime in seconds. When it is nil, the API key does not expire.
+    def create_api_key(name, scopes: [], expires_in: nil)
+      @created_api_key_id = nil
+      3.times do |attempt|
+        api_key = generate_api_key
+        hash = api_key_insert_hash(api_key, name, scopes, expires_in)
+        error = raised_uniqueness_violation { @created_api_key_id = api_keys_table_ds.insert(hash) }
+        return api_key unless error
+
+        # Two equal digests are almost impossible. Try again with a new API key.
+        raise error if attempt == 2
+      end
+    end
+
+    private
+
+    def api_key_insert_hash(api_key, name, scopes, expires_in)
+      hash = {
+        api_keys_account_id_column => account_id,
+        api_keys_name_column => name,
+        api_keys_digest_column => api_key_digest(api_key),
+        api_keys_hint_column => api_key_hint(api_key),
+        api_keys_scopes_column => (scopes.join(" ") unless scopes.empty?)
+      }
+      if expires_in
+        # The database calculates the expiration time with its own clock, as Rodauth does for deadlines.
+        hash[api_keys_expires_at_column] = Sequel.date_add(Sequel::CURRENT_TIMESTAMP, seconds: expires_in)
+      end
+      hash
+    end
+
+    def use_date_arithmetic?
+      true
+    end
+
+    # A closed account must not use its API keys.
+    # If close_account calls delete_account, remove the API key rows first, because of the foreign key.
+    def after_close_account
+      super if defined?(super)
+      if delete_account_on_close?
+        api_keys_ds.delete
+      else
+        revoke_all_api_keys
+      end
+    end
+
+    # Do not send a JWT in a response to a request that an API key authenticated.
+    # Such a JWT would authenticate the account without the API key, also after the revocation of the API key.
+    def set_jwt
+      super unless @api_key_row
+    end
+
+    # Return the items for the rows of the dataset, the newest first.
+    def api_key_items(ds)
+      status = Sequel.case(
+        [
+          [{api_keys_revoked_at_column => nil}, Sequel.case([[active_api_key_condition, "active"]], "expired")]
+        ],
+        "revoked"
+      )
+      ds.select_append(status.as(:api_key_status)).reverse(api_keys_id_column).map do |row|
+        {
+          id: row[api_keys_id_column],
+          name: row[api_keys_name_column],
+          hint: row[api_keys_hint_column],
+          scopes: row[api_keys_scopes_column].to_s.split(" "),
+          created_at: convert_timestamp(row[api_keys_created_at_column]),
+          last_use: convert_timestamp(row[api_keys_last_use_column]),
+          expires_at: convert_timestamp(row[api_keys_expires_at_column]),
+          revoked_at: convert_timestamp(row[api_keys_revoked_at_column]),
+          status: row[:api_key_status].to_sym
+        }
+      end
+    end
+
+    def api_key_json(api_key)
+      api_key.transform_keys(&:to_s).merge(
+        "status" => api_key[:status].to_s,
+        "created_at" => api_key[:created_at]&.iso8601,
+        "last_use" => api_key[:last_use]&.iso8601,
+        "expires_at" => api_key[:expires_at]&.iso8601,
+        "revoked_at" => api_key[:revoked_at]&.iso8601
+      )
+    end
+
+    def template_path(page)
+      path = File.expand_path("../../../templates/#{page}.str", __dir__)
+      File.file?(path) ? path : super
+    end
+
+    # An API key must not use the Rodauth routes. It must not manage the account or its API keys.
+    # Send a 403 response for a request that an API key authenticated.
+    def require_api_key_management_session
+      return unless api_key_authenticated?
+
+      set_response_error_reason_status(:api_key_management_not_permitted, api_key_management_not_permitted_error_status)
+      return_api_key_error_response(api_key_management_not_permitted_message)
+    end
+
+    def api_key_name_param_value
+      name = param(api_key_name_param).strip
+      unless valid_api_key_name?(name)
+        throw_error_reason(:invalid_api_key_name, invalid_field_error_status, api_key_name_param, invalid_api_key_name_message)
+      end
+      name
+    end
+
+    # The parameter can be an array (HTML check boxes or JSON) or a string with scopes separated by spaces.
+    def api_key_scopes_param_value
+      scopes = case (value = raw_param(api_key_scopes_param))
+      when nil then []
+      when Array then value.uniq
+      when String then value.split.uniq
+      end
+
+      unless scopes && valid_api_key_scopes?(scopes)
+        throw_error_reason(:invalid_api_key_scopes, invalid_field_error_status, api_key_scopes_param, invalid_api_key_scopes_message)
+      end
+      if scopes.empty? && !api_key_scopes.empty?
+        throw_error_reason(:api_key_scopes_required, invalid_field_error_status, api_key_scopes_param, api_key_scopes_required_message)
+      end
+      scopes
+    end
+
+    # Return the lifetime in seconds, or nil for an API key that does not expire.
+    def api_key_expires_in_param_value
+      value = param(api_key_expires_at_param).strip
+      if value.empty?
+        if api_key_max_lifetime
+          throw_error_reason(:api_key_expires_at_required, invalid_field_error_status, api_key_expires_at_param, api_key_expires_at_required_message)
+        end
+        return
+      end
+
+      unless (expires_at = parse_api_key_expires_at(value))
+        throw_error_reason(:invalid_api_key_expires_at, invalid_field_error_status, api_key_expires_at_param, invalid_api_key_expires_at_message)
+      end
+
+      expires_in = (expires_at - Time.now).ceil
+      if expires_in <= 0
+        throw_error_reason(:api_key_expires_at_past, invalid_field_error_status, api_key_expires_at_param, api_key_expires_at_past_message)
+      end
+      if api_key_max_lifetime && expires_in > api_key_max_lifetime
+        throw_error_reason(:api_key_expires_at_too_late, invalid_field_error_status, api_key_expires_at_param, api_key_expires_at_too_late_message)
+      end
+      expires_in
+    end
+
+    # Find the active API key and its account. Return the session hash for the request.
+    def api_key_session(api_key)
+      digests = api_key_digests(api_key)
+      row = api_keys_table_ds.where(api_keys_digest_column => digests).where(active_api_key_condition).first
+      invalid_api_key_response unless row
+
+      # The account must exist and be open. Do not use the status filter of a cookie session.
+      # The verify_account_grace_period feature adds unverified accounts to that filter.
+      # Do not keep the account. A Rodauth route loads it again and shows a warning when it loads it two times.
+      @session = {
+        session_key => row[api_keys_account_id_column],
+        authenticated_by_session_key => ["api_key"],
+        api_key_id_session_key => row[api_keys_id_column]
+      }
+      invalid_api_key_response unless api_key_account_open?(row[api_keys_account_id_column])
+
+      @api_key_row = row
+      if hmac_secret_rotation? && row[api_keys_digest_column] != digests.first
+        api_keys_table_ds.where(api_keys_id_column => row[api_keys_id_column]).update(api_keys_digest_column => digests.first)
+      end
+      update_api_key_last_use
+      set_api_key_expiration_header
+      @session
+    end
+
+    # Tell the client when the API key expires. An API key without an expiration time gets no header.
+    def set_api_key_expiration_header
+      return unless (header = api_key_expiration_header)
+      return unless (expires_at = convert_timestamp(@api_key_row[api_keys_expires_at_column]))
+
+      set_response_header(header, api_key_expiration_header_value(expires_at))
+    end
+
+    def api_key_account_open?(id)
+      ds = account_ds(id)
+      ds = ds.where(account_status_column => account_open_status_value) unless skip_status_checks?
+      !ds.empty?
+    end
+
+    def invalid_api_key_response
+      @session = {}
+      @account = nil
+      set_response_error_reason_status(:invalid_api_key, invalid_key_error_status)
+      set_response_header("www-authenticate", "Bearer realm=\"#{api_key_realm}\", error=\"invalid_token\"")
+      return_api_key_error_response(invalid_api_key_message)
+    end
+
+    # Send the error message as JSON when the application enables the json feature and the request uses JSON.
+    # Otherwise, send it as plain text.
+    def return_api_key_error_response(message)
+      if respond_to?(:use_json?) && use_json?
+        json_response[json_response_error_key] = message
+        return_json_response
+      else
+        response.headers[convert_response_header_key("content-type")] = "text/plain"
+        return_response(message)
+      end
+    end
+
+    # Do not clear the cookie session for a request that an API key authenticated.
+    def use_scope_clear_session?
+      super && !api_key_authenticated?
+    end
+
+    # All API keys in the table, for all accounts.
+    def api_keys_table_ds
+      db[api_keys_table]
+    end
+
+    # All API keys of the account.
+    def api_keys_ds(id = account_id)
+      api_keys_table_ds.where(api_keys_account_id_column => id)
+    end
+
+    # The API keys of the account that are not revoked and not expired.
+    def active_api_keys_ds(id = account_id)
+      api_keys_ds(id).where(active_api_key_condition)
+    end
+
+    # An API key is active when it is not revoked and not expired.
+    def active_api_key_condition
+      expires_at = Sequel[api_keys_expires_at_column]
+      Sequel.&(
+        {api_keys_revoked_at_column => nil},
+        Sequel.|({expires_at => nil}, expires_at > Sequel::CURRENT_TIMESTAMP)
+      )
+    end
+  end
+end
+
+# With rodauth-model, the account model gets an api_keys association.
+if defined?(Rodauth::Model)
+  Rodauth::Model.register_association(:api_keys) do
+    {name: :api_keys, type: :many, table: api_keys_table, key: api_keys_account_id_column}
+  end
+end

data/templates/api-key-created.str

@@ -0,0 +1,5 @@
+<div class="form-group mb-3">
+  <label for="api-key" class="form-label">#{rodauth.api_key_label}</label>
+  <input type="text" class="form-control" id="api-key" readonly="readonly" autocomplete="off" value="#{h rodauth.created_api_key}"/>
+</div>
+<p><a href="#{rodauth.api_keys_path}" id="api-keys-link">#{rodauth.api_keys_page_title}</a></p>

data/templates/api-keys.str

@@ -0,0 +1,30 @@
+#{(api_keys = rodauth.account_api_keys).empty? ? "<p id=\"api-keys-empty\">#{rodauth.api_keys_empty_message}</p>" : nil}
+#{unless api_keys.empty?
+  format_time = lambda { |time| time ? h(time.strftime(rodauth.strftime_format)) : rodauth.api_key_never_label }
+  status_label = {active: rodauth.api_key_active_label, expired: rodauth.api_key_expired_label, revoked: rodauth.api_key_revoked_label}
+  show_scopes = !rodauth.api_key_scopes.empty?
+  rows = api_keys.map do |api_key|
+    "<tr id=\"api-key-#{h api_key[:id]}\" class=\"api-key-#{api_key[:status]}\">" \
+      "<td>#{h api_key[:name]}</td>" \
+      "<td><code>#{h api_key[:hint]}&hellip;</code></td>" \
+      "#{"<td>#{h api_key[:scopes].join(" ")}</td>" if show_scopes}" \
+      "<td>#{format_time.call(api_key[:created_at])}</td>" \
+      "<td>#{format_time.call(api_key[:last_use])}</td>" \
+      "<td>#{format_time.call(api_key[:expires_at])}</td>" \
+      "<td>#{status_label[api_key[:status]]}</td>" \
+    "</tr>"
+  end.join("\n")
+  "<table class=\"table\" id=\"api-keys\"><thead><tr>" \
+    "<th>#{rodauth.api_key_name_label}</th>" \
+    "<th>#{rodauth.api_key_label}</th>" \
+    "#{"<th>#{rodauth.api_key_scopes_label}</th>" if show_scopes}" \
+    "<th>#{rodauth.api_key_created_at_label}</th>" \
+    "<th>#{rodauth.api_key_last_use_label}</th>" \
+    "<th>#{rodauth.api_key_expires_at_label}</th>" \
+    "<th>#{rodauth.api_key_status_label}</th>" \
+  "</tr></thead><tbody>#{rows}</tbody></table>"
+end}
+<p>
+  <a href="#{rodauth.create_api_key_path}" id="create-api-key-link">#{rodauth.create_api_key_link_text}</a>
+  #{"<a href=\"#{rodauth.revoke_api_key_path}\" id=\"revoke-api-key-link\">#{rodauth.revoke_api_key_link_text}</a>" if api_keys.any? { |api_key| api_key[:status] == :active }}
+</p>

data/templates/create-api-key.str

@@ -0,0 +1,24 @@
+<form method="post" class="rodauth" role="form" id="create-api-key-form">
+  #{rodauth.create_api_key_additional_form_tags}
+  #{rodauth.csrf_tag}
+  <div class="form-group mb-3">
+    <label for="api-key-name" class="form-label">#{rodauth.api_key_name_label}#{rodauth.input_field_label_suffix}</label>
+    #{rodauth.input_field_string(rodauth.api_key_name_param, "api-key-name", :attr=>"maxlength=\"#{rodauth.api_key_name_max_length}\"")}
+  </div>
+  <div class="form-group mb-3">
+    <label for="api-key-expires-at" class="form-label">#{rodauth.api_key_expires_at_label}#{rodauth.input_field_label_suffix}</label>
+    #{rodauth.input_field_string(rodauth.api_key_expires_at_param, "api-key-expires-at", :type=>"date", :required=>!!rodauth.api_key_max_lifetime)}
+  </div>
+  #{unless rodauth.api_key_scopes.empty?
+    selected = Array(rodauth.raw_param(rodauth.api_key_scopes_param))
+    checkboxes = rodauth.api_key_scopes.map do |scope|
+      id = "api-key-scope-#{h scope}"
+      checked = 'checked="checked"' if selected.include?(scope)
+      input = rodauth.input_field_string("#{rodauth.api_key_scopes_param}[]", id, :type=>"checkbox", :class=>"form-check-input", :value=>h(scope), :required=>false, :skip_error_message=>true, :attr=>checked)
+      "<div class=\"form-check\">#{input}<label class=\"form-check-label\" for=\"#{id}\">#{h scope}</label></div>"
+    end.join("\n")
+    "<fieldset class=\"form-group mb-3\"><legend class=\"form-label\">#{rodauth.api_key_scopes_label}</legend>#{checkboxes}#{rodauth.formatted_field_error(rodauth.api_key_scopes_param)}</fieldset>"
+  end}
+  #{rodauth.render('password-field') if rodauth.modifications_require_password?}
+  #{rodauth.button(rodauth.create_api_key_button)}
+</form>

data/templates/revoke-api-key.str

@@ -0,0 +1,19 @@
+#{(active_api_keys = rodauth.account_api_keys.select { |api_key| api_key[:status] == :active }).empty? ? "<p id=\"no-active-api-keys\">#{rodauth.no_active_api_keys_message}</p>" : nil}
+#{unless active_api_keys.empty?
+  last_id = active_api_keys.last[:id]
+  radios = active_api_keys.map do |api_key|
+    id = "api-key-id-#{h api_key[:id]}"
+    input = rodauth.input_field_string(rodauth.api_key_id_param, id, :type=>"radio", :class=>"form-check-input", :skip_error_message=>true, :value=>h(api_key[:id]), :required=>false)
+    last_use = api_key[:last_use] ? h(api_key[:last_use].strftime(rodauth.strftime_format)) : rodauth.api_key_never_label
+    label = "<label class=\"form-check-label\" for=\"#{id}\">#{h api_key[:name]} (<code>#{h api_key[:hint]}&hellip;</code>), #{rodauth.api_key_last_use_label}: #{last_use}</label>"
+    error = rodauth.formatted_field_error(rodauth.api_key_id_param) if api_key[:id] == last_id
+    "<div class=\"form-check radio\">#{input}#{label}#{error}</div>"
+  end.join("\n")
+  "<form method=\"post\" class=\"rodauth\" role=\"form\" id=\"revoke-api-key-form\">" \
+    "#{rodauth.revoke_api_key_additional_form_tags}" \
+    "#{rodauth.csrf_tag}" \
+    "<fieldset class=\"form-group mb-3\">#{radios}</fieldset>" \
+    "#{rodauth.render("password-field") if rodauth.modifications_require_password?}" \
+    "#{rodauth.button(rodauth.revoke_api_key_button, :class=>"btn btn-danger")}" \
+  "</form>"
+end}

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: rodauth-api_keys
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pavel Dušánek
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rodauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.48'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.48'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: The api_keys feature for Rodauth lets an account create, list, and revoke
+  API keys. A client sends an API key in the Authorization header to authenticate
+  a request.
+email:
+- dusanek@iquest.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rodauth/features/api_keys.rb
+- templates/api-key-created.str
+- templates/api-keys.str
+- templates/create-api-key.str
+- templates/revoke-api-key.str
+homepage: https://github.com/dush/rodauth-api_keys
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/dush/rodauth-api_keys
+  changelog_uri: https://github.com/dush/rodauth-api_keys/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: API keys feature for Rodauth
+test_files: []