Keyper
This engine adds basic API functionality to a Ruby on Rails application. It enables mobile apps to login to your web service, request a set of API credentials, and then authenticate subsequent requests with key and secret headers.
Compatibility
Keyper has been built with common Rails authentication practices in mind, and can work well with tools such as has_secure_password or Authlogic.
Broadly speaking, Keyper assumes your application has User
and UserSession
models, as well as the following controller methods:
require_user
current_user
current_user_session
Installation
Add this line to your application's Gemfile:
gem 'keyper'
And then execute:
$ bundle
Or install it yourself as:
$ gem install keyper
Usage
Mount the engine in our application's routes.rb
file. This will determine the base path for API login.
Rails.application.routes.draw do
mount Keyper::Engine => "/api"
end
API key authentication is not enabled globally. Instead, you should include the Keyper::ApiKeyAuthentication
module selectively in any controllers you wish to expose.
class ProtectedStuffController < ApplicationController
include Keyper::ApiKeyAuthentication
before_action :require_user
end
You can then optionally configure the engine, or leave it at the default settings.
Keyper.configure do |config|
config.invalidate_keys_on_password_change = true
config.attribute_refresh_interval = 1.minute
end
Authentication
Your mobile application should first attempt to create an API key. Make a POST request to the /api/api_keys
endpoint, passing :username
and :password
parameters.
curl -X POST -F 'user_session[username]=username' -F 'user_session[password]=password' http://localhost:3000/api/api_keys
Sample response:
{
"api_key":"06e374a582721189a58192413190600a",
"api_secret":"6240aa5521b44041d6a6874bf1001852"
}
Store those values securely in your application. You can then make authenticated requests by passing those values as Api-Key
and Api-Secret
headers, respectively.
curl --header "Api-Key: 06e374a582721189a58192413190600a" --header "Api-Secret: 6240aa5521b44041d6a6874bf1001852" http://localhost:3000/protected_stuff
You can hit the /api/api_keys/check
endpoint to quickly check the validity of your keys. A 200 response means your keys are good.
curl --header "Api-Key: 06e374a582721189a58192413190600a" --header "Api-Secret: 6240aa5521b44041d6a6874bf1001852" http://localhost:3000/api/api_keys/check
When your user logs out, it is a good idea to delete the associated API key. You can do that by making a DELETE request. Pass the key and secret headers as you normally would, then specify which key you wish to delete in the restful url parameter.
curl -X DELETE \
--header "Api-Key: 06e374a582721189a58192413190600a" \
--header "Api-Secret: 6240aa5521b44041d6a6874bf1001852" \
http://localhost:3000/api/api_keys/06e374a582721189a58192413190600a