rails_api_keys

Reusable Rails engine for personal API keys: create (reveal once), hash at rest, revoke, and authenticate via Authorization: Bearer <token>.

Host apps own UI, routes, and domain APIs. This gem stays thin on purpose.

• RailsApiKeys::ApiKey — issue, authenticate, revoke
• has_api_keys — opt-in owner macro with create_api_key! (supports multiple models)
• RailsApiKeys::Authentication — controller concern for Bearer tokens
• Install generator (migration + initializer)

No mailers, jobs, views, assets, or mounted domain routes.

Add the gem and install:

# Gemfile
gem "rails_api_keys"

bundle install
bin/rails generate rails_api_keys:install
bin/rails db:migrate

Opt in on each owner model with has_api_keys (any number of models):

class User < ApplicationRecord
  has_api_keys
end

class Company < ApplicationRecord
  has_api_keys
end

That declares has_many :api_keys and allows the model to own keys. Build your own controllers/UI to create keys (show the raw token once), list them, and revoke — or use the optional companion gem below.

For a ready-made HTML/JSON management UI (create, reveal once + copy, list active keys, revoke), install the companion gem rails_api_keys-ui:

# Gemfile
gem "rails_api_keys"
gem "rails_api_keys-ui"

See that repo for install generators, route helpers, embeddable panel, and configuration.

Defaults suit a typical Devise User host; multiple owners are supported via has_api_keys:

Override only what you need:

# config/initializers/rails_api_keys.rb
RailsApiKeys.configure do |config|
  # config.token_prefix = "myapp_ak_"
  # config.owner_active = ->(owner) { owner.active? }
end

key, raw = current_user.create_api_key!(name: "Zapier", permission: :read)
# Show `raw` once — it cannot be recovered later.

RailsApiKeys::ApiKey.authenticate(raw) # => key or nil
key.revoke!

class Api::V1::BaseController < ActionController::API
  include RailsApiKeys::Authentication

  before_action :authenticate_api_key!

  # current_api_key / current_api_owner are available after authenticate
end

Clients send:

Authorization: Bearer <raw_token>

authenticate_api_key! rejects missing/invalid tokens with 401, then enforces permission from the HTTP method: GET/HEAD require read; other methods require write (403 if the key lacks it).

Permissions are immutable after create. Revoke with revoke! (sets revoked_at).

• Raw tokens are returned only from create_api_key! / generate_for! and never stored
• Digests use SHA-256 (token_digest); UI can show token_display_prefix
• Soft revoke via revoked_at; authentication ignores revoked keys

bundle install
bundle exec rspec
bin/rubocop

See CHANGELOG.md for release notes. Agent-oriented notes live in AGENTS.md.

Bug reports and pull requests are welcome. See CONTRIBUTING.md and the Code of Conduct.

To report a security vulnerability privately, see SECURITY.md.

This project is licensed under the MIT License.

Rubyroid Labs — full-cycle software development company for businesses delivering scalable web and mobile apps, dedicated developers, and full-cycle teams in Ruby on Rails, React Native, and UX/UI. 98% on-time delivery.

• Website: rubyroidlabs.com
• Email: hi@rubyroidlabs.com
• References: Clutch