Thank you for choosing Clerk for your authentication, session & user management needs!
This SDK allows you to call the Clerk Backend API from Ruby code without having to implement the calls yourself.
Note: You're looking at the main branch, which requires that you use Auth v2.
If you're looking for the legacy authentication scheme, refer to the
v1
branch.
Clerk is Hiring!
Would you like to work on Open Source software and help maintain this repository? Apply today https://apply.workable.com/clerk-dev/.
Add this line to your application's Gemfile:
gem 'clerk-sdk-ruby', require: "clerk"
And then execute:
$ bundle install
Or install it yourself as:
$ gem install clerk-sdk-ruby
First, you need to get an API key for a Clerk instance. This is done via the Clerk dashboard.
Then you can instantiate a Clerk::SDK
instance and access all
Backend API endpoints.
Here's a quick example:
clerk = Clerk::SDK.new(api_key: "your_api_key")
# List all users
clerk.users.all
# Get your first user
user = clerk.users.all(limit: 1).first
# Extract their primary email address ID
email_id = user["primary_email_address_id"]
# Send them a welcome email
clerk.emails.create(
email_address_id: email_id,
from_email_name: "welcome",
subject: "Welcome to MyApp",
body: "Welcome to MyApp, #{user["first_name"]}",
)
The SDK can be configured in three ways: environment variables, configuration singleton and constructor arguments. The priority goes like this:
- Constructor arguments
- Configuration object
- Environment variables
If an argument is not provided, the configuration object is looked up, which falls back to the associated environment variable. Here's an example with all supported configuration settings their environment variable equivalents:
Clerk.configure do |c|
c.api_key = "your_api_key" # if omitted: ENV["CLERK_API_KEY"] - API calls will fail if unset
c.base_url = "https://..." # if omitted: "https://api.clerk.dev/v1/"
c.logger = Logger.new(STDOUT) # if omitted, no logging
c.middleware_cache_store = ActiveSupport::Cache::FileStore.new("/tmp/clerk_middleware_cache") # if omitted: no caching
end
You can customize each instance of the Clerk::SDK
object by passing keyword
arguments to the constructor:
clerk = Clerk::SDK.new(
api_key: "X",
base_url: "Y",
logger: Logger.new()
)
For full customization, you can instead pass a Faraday
object directly, which
will ignore all the other arguments, if passed:
faraday = Faraday.new()
clerk = Clerk::SDK.new(connection: faraday)
Refer to the Faraday documentation for details.
The SDK comes with a Rack middleware which lazily loads the Clerk session and
user. It inserts a clerk
key in the Rack environment, which is an instance
of Clerk::Proxy
. To get the session or the user of the session, you call
session
or user
respectively. In case there is no session, you can retrieve
the API error with the error
getter method.
The SDK will automatically add the Rack middleware to the
middleware stack. For easier access to the Clerk session and user, include the
Clerk::Authenticatable
concern in your controller:
require "clerk/authenticatable"
class ApplicationController < ActionController::Base
include Clerk::Authenticatable
end
This gives your controller and views access to the following methods:
clerk_session
clerk_user
clerk_user_signed_in?
The API client depends on the excellent Faraday gem for HTTP requests. You can swap out the original implementation with your own customized instance.
The API client sends all requests as application/x-www-form-urlencoded
. The
API then responds with JSON which is then converted and returned as a Ruby
Hash
, or Array
of hashes. Errors are also returned as a JSON object, with a
single key (errors
) containing an array of error objects.
Read the API documentation for details on expected parameters and response formats.
After checking out the repo, run bin/setup
to install dependencies. Then, run
bundle exec rake
to run the tests. You can also run bin/console
for an
interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To
release a new version, update the version number in version.rb
, and then run
bundle exec rake release
, which will create a git tag for the version, push
git commits and the created tag, and push the .gem
file to
rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/clerkinc/clerk-sdk-ruby.
The gem is available as open source under the terms of the MIT License.