No commit activity in last 3 years
No release in over 3 years
This gem provides views to add users (probably front-end or mobile developers) to your Rails 5 so they can create clients and manage tokens. With this, you can authenticate all requests and eventually track usage by each client.



 Project Readme

Client Manager

Client Manager

Client Manager is a mountable Rails (engine) gem that helps identify and authenticate your API clients.


To understand why this gem exists, let's look at a simple example of a blog application built with a Rails API and any JavaScript front-end framework. In the API, you're probably going to have some endpoints that only logged in Users/Authors can access. Like creating or deleting a blog post. Other endpoints, however, like reading posts, will be unauthenticated. This means that if one should go to the read endpoint using a browser, the whole JSON response will be displayed. What would be ideal, would be make it such that only the front-end application can access the read endpoint(s).

Typically to do this, you might generate a random UUID and ask the front-end developer to put it in the header of their requests. But this doesn't scale well. What if you want to add an Android app? Or an iOS one too? That's where Client Manager comes in. It helps you easily manage all of this with a simple User Interface. With Client Manager, you can:

  • Create clients with an automatically generated JSON Web Token, which can be used to authenticate requests
  • Create users with the ability to create (a specified number of) clients themselves


  • Rails 5 and above

Installation & Setup

1. Add the gem to your Gemfile

Add the following line to your application's Gemfile:

gem 'client_manager', '~> 0.1.0'


bundle install

2. Migrate the database

Run the following command in your terminal:

rake db:migrate

3. Install Client Manager

Run the following command in your terminal:

rails generate client_manager:install

This creates a client_manager.rb file in your app's initializer's folder and inserts include ClientManager::Concerns::SetClientByToken into your ApplicationController to authenticate all requests. You can remove it from that controller and put it in any controller that needs client authentication.

Note if your app is an API-only application, Client Manager will do the following:

  • Remove config.api_only = true from application.rb
  • Add config.middleware.use ActionDispatch::Flash to application.rb
  • Uncomment # require "sprockets/railtie" in application.rb

In your client_manager.rb file, you need to set config.token_secret (to a random secure UUID). It's set to nil by default and would raise an error if you try to create clients without setting it.

4. Create a SuperAdmin Account

Finally, you need to create a superadmin account for yourself using the following command:


For example:

rake client_manager:superadmin NAME=Timi EMAIL=timi@example.com PASSWORD=lol

All three arguments are required.

5. Start your server


The Client Manager is automatically hosted at /client_manager. There, you can sign in with your superadmin credentials and start using the application.

Creating Users

Once, signed in, you can create Client Manager Users and specify the maximum number of clients they are allowed to create. Users you create will get an email with their password and are required to change this on first sign in.

Creating a User

Note: Client Manager inherits from your application's ActionMailer settings. If you've not set up your application to send emails, client manager emails WILL NOT get sent. You can see the email content in your server logs. Read more about ActionMailer.

Creating Clients

You can create clients yourself, or let your users create clients. To create a Client, click the server icon in the navigation to go to the Clients page. Then, click the plus sign to create a new client.

Creating a Client

Authenticating Requests

Client applications need to add their generated tokens to the Header of every request. For example -

fetch(apiUrl, {
    method: 'GET',
    headers: new Headers({ 'client_token': GENERATED_TOKEN_HERE })

You can access the client making the request within your controllers using the current_client helper method.

Contributing & Todo

To contribute: fork this repo, write code & make pull request. Some of the things I'm looking at doing in the immediate future are:

  • Tests
  • Basic stats: Requests per client over time
  • Rate limiting client requests


The gem is available as open source under the terms of the MIT License.