Create a Clerk application
Install Ruby
Instantiate a Clerk::SDK instance
Configuration

Clerk Ruby SDK

Create a Clerk application

You need to create a Clerk application in your Clerk Dashboard before you can set up Clerk Ruby. For more information, check out our Set up your application guide.

Install Ruby

Once a Clerk application has been created, you can install and then start using Clerk Ruby in your application.

Add this line to your application's Gemfile.

gem 'clerk-sdk-ruby', require: "clerk"

And then execute:

terminal

$ bundle install

Or install it yourself as:

terminal

$ gem install clerk-sdk-ruby

Instantiate a `Clerk::SDK` instance

To access all Backend API endpoints, you need to instantiate a Clerk::SDK instance.

You will need your Clerk secret key to instantiate an instance. Go to the Clerk Dashboard and navigate to the API Keys page and copy your secret key.

This examples shows how to instantiate an instance of Clerk::SDK with your secret key and then send your first user a welcome email.

clerk = Clerk::SDK.new(api_key: `YOUR_SECRET_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:

Constructor arguments
Configuration object
Environment variables

Constructor arguments

You can customize each instance of the Clerk::SDK object by passing keyword arguments to the constructor:

clerk = Clerk::SDK.new(
    api_key: `YOUR_SECRET_KEY`,
    base_url: "Y",
    logger: Logger.new()
)

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_SECRET_KEY` # if omitted: ENV["CLERK_SECRET_KEY"] - API calls will fail if unset
  c.base_url = "https://..." # if omitted: "https://api.clerk.com/v1/"
  c.logger = Logger.new(STDOUT) # if omitted, no logging
  c.middleware_cache_store = Rails.cache # if omitted: no caching
end

Refer to the Faraday documentation for details.

Environment variables

Here's a list of all environment variables the SDK uses:

Variable name	Usage
`CLERK_API_BASE`	Overrides the default API base URL: `https://api.clerk.com/v1/`
`CLERK_SECRET_KEY`	The Secret key of your instance (required)
`CLERK_SIGN_IN_URL`	Rails view helper: `clerk_sign_in_url`
`CLERK_SIGN_IN_UP`	Rails view helper: `clerk_sign_up_url`
`CLERK_USER_PROFILE_URL`	Rails view helper: `clerk_user_profile_url`

Edit this page on GitHub

Last updated on Aug 20, 2024