Clerk Ruby SDK

This SDK allows you to call the Clerk Backend API from Ruby code without having to implement the calls yourself.

---

Clerk is Hiring!

Would you like to work on Open Source software and help maintain this repository? Apply today!

---

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.

Installation

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

Quick Start

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"]}",
)

Configuration

The SDK can be configured in three ways: environment variables, configuration singleton and constructor arguments. The priority goes like this:

1. Constructor arguments
2. Configuration object
3. 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_SECRET_KEY"] - API calls will fail if unset
  c.base_url = "https://..." # if omitted: ENV["CLERK_API_BASE"] - defaults to "https://api.clerk.com/v1/"
  c.publishable_key = "pk_(test|live)_...." # if omitted: ENV["CLERK_PUBLISHABLE_KEY"] - Handshake mechanism (check section below) will fail if unset
  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
  c.excluded_routes ["/foo", "/bar/*"]
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.

Rack middleware

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.

Rails integration

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?

Internals

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.

Handshake

The Client Handshake is a mechanism that is used to resolve a request’s authentication state from “unknown” to definitively signed in or signed out. Clerk’s session management architecture relies on a short-lived session JWT to validate requests, along with a long-lived session that is used to keep the session JWT fresh by interacting with the Frontend API. The long-lived session token is stored in an HttpOnly cookie associated with the Frontend API domain. If a short-lived session JWT is expired on a request to an application’s backend, the SDK doesn’t know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers the handshake.

With the handshake, we can resolve the authentication state on the backend and ensure the request is properly handled as signed in or out, instead of being in a potentially “unknown” state. The handshake flow relies on redirects to exchange session information between FAPI and the application, ensuring the resolution of unknown authentication states minimizes performance impact and behaves consistently across different framework and language implementations.

Development

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.

Release

To release a new version:

• update the version number in version.rb
• update CHANGELOG.md to include information about the changes
• merge changes into main
• run bundle exec rake release

If gem publishing is NOT executed automatically:

• run gem push pkg/clerk-sdk-ruby-{version}.gem to push the .gem file to rubygems.org

The bundle exec rake release command:

• creates a git tag with the version found in version.rb
• pushes the git tag

Yank release

We should avoid yanking a releasing but if it's necessary execute gem yank clerk-sdk-ruby -v {version}

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/clerkinc/clerk-sdk-ruby.

License

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