Project

rails_api_keys

0.0
The project is in a healthy, maintained state
rails_api_keysrubyroidlabs/rails_api_keysHomepageDocumentationSource CodeBug Tracker
Thin Rails engine for personal API keys: issue a raw token once, store a SHA-256 digest, soft-revoke, and authenticate ActionController::API requests with Authorization: Bearer. Host apps own UI, routes, and domain APIs.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
329
Stars
1
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2026-08-10
Latest release
2026-08-10
 Pull Requests
Open Pull Requests
2
Closed Pull Requests
0
Merged Pull Requests
0
Pull Request Acceptance Rate
0%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-08-10
Reverse Dependencies
0

 Dependencies

Runtime

rails
>= 7.0
 Project Readme

rails_api_keys

CI

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.

What this gem includes

  • RailsApiKeys::ApiKey — issue, authenticate, revoke
  • RailsApiKeys::Authentication — controller concern for Bearer tokens
  • Install generator (migration + initializer)

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

Installation

Add the gem and install:

# Gemfile
gem "rails_api_keys"
bundle install
bin/rails generate rails_api_keys:install
bin/rails db:migrate

Until the gem is published on RubyGems, you can use git or a local path:

gem "rails_api_keys", git: "https://github.com/rubyroidlabs/rails_api_keys.git"
# or: gem "rails_api_keys", path: "../rails_api_keys"

Host setup

On the owner model (defaults to User):

class User < ApplicationRecord
  has_many :api_keys, as: :owner, class_name: "RailsApiKeys::ApiKey", dependent: :destroy
end

Build your own controllers/UI to create keys (show the raw token once), list them, and revoke.

Configuration

Defaults suit a typical Devise User host:

Option Default Purpose
owner_class "User" Expected owner class name
token_prefix "#{AppName.downcase}_ak_" Prefix on generated raw tokens
owner_active active_for_authentication? when present Reject keys whose owner is inactive

Override only what you need:

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

Usage

key, raw = RailsApiKeys::ApiKey.generate_for!(
  owner: current_user,
  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!
  before_action -> { require_api_permission!(:read) }

  # current_api_key / current_api_owner are available after authenticate
end

Clients send:

Authorization: Bearer <raw_token>

Permissions

Permission allows_read? allows_write?
read yes no
read_write yes yes

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

Security notes

  • Raw tokens are returned only from 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

Development

bundle install
bundle exec rspec
bin/rubocop

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

License

This project is licensed under the MIT License.

Rubyroid Labs

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.