{"id":13878823,"url":"https://github.com/clerk/clerk-sdk-ruby","last_synced_at":"2026-01-12T00:45:12.097Z","repository":{"id":41967077,"uuid":"368861401","full_name":"clerk/clerk-sdk-ruby","owner":"clerk","description":"Access the Clerk Backend API from Ruby","archived":false,"fork":false,"pushed_at":"2025-02-26T20:56:37.000Z","size":293,"stargazers_count":27,"open_issues_count":1,"forks_count":10,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-14T23:15:16.471Z","etag":null,"topics":["authentication","authentication-middleware","sdk","sdk-ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clerk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-19T12:28:34.000Z","updated_at":"2025-02-26T20:56:39.000Z","dependencies_parsed_at":"2023-11-22T14:34:56.718Z","dependency_job_id":"a379d1b7-adb8-4ead-ba81-ca064716e5db","html_url":"https://github.com/clerk/clerk-sdk-ruby","commit_stats":null,"previous_names":["clerk/clerk-sdk-ruby","clerkinc/clerk-sdk-ruby"],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Fclerk-sdk-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Fclerk-sdk-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Fclerk-sdk-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clerk%2Fclerk-sdk-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clerk","download_url":"https://codeload.github.com/clerk/clerk-sdk-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244367438,"owners_count":20441887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authentication-middleware","sdk","sdk-ruby"],"created_at":"2024-08-06T08:02:01.203Z","updated_at":"2025-10-16T23:55:39.511Z","avatar_url":"https://github.com/clerk.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.clerk.com/?utm_source=github\u0026utm_medium=starter_repos\u0026utm_campaign=sdk_ruby\" target=\"_blank\" align=\"center\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./docs/clerk-logo-dark.png\"\u003e\n      \u003cimg src=\"./docs/clerk-logo-light.png\" height=\"64\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n\u003c/p\u003e\n\n# Clerk Ruby SDK\n\nThis SDK allows you to call the [Clerk](https://www.clerk.com/?utm_source=github\u0026utm_medium=starter_repos\u0026utm_campaign=sdk_ruby) Backend API from Ruby code without having to implement the calls yourself.\n\n[![chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://discord.com/invite/b5rXHjAg7A)\n[![documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs)\n[![twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev)\n\n---\n\n**Clerk is Hiring!**\n\nWould you like to work on Open Source software and help maintain this repository? [Apply today!](https://apply.workable.com/clerk-dev/)\n\n---\n\n**Note**: You're looking at the main branch, which requires that you use [Auth\nv2](https://clerk.com/docs/upgrade-guides/auth-v2).\n\nIf you're looking for the legacy authentication scheme, refer to the\n[`v1`](https://github.com/clerkinc/clerk-sdk-ruby/tree/v1) branch.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'clerk-sdk-ruby', require: \"clerk\"\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install clerk-sdk-ruby\n\n## Quick Start\n\nFirst, you need to get an API key for a Clerk instance. This is done via the\n[Clerk dashboard](https://dashboard.clerk.com/applications).\n\nThen you can instantiate a `Clerk::SDK` instance and access all\n[Backend API](https://clerk.com/docs/reference/backend-api) endpoints.\nHere's a quick example:\n\n```ruby\nclerk = Clerk::SDK.new(api_key: \"your_api_key\")\n# List all users\nclerk.users.get_user_list\n# Get your first user\nuser = clerk.users.get_user_list(limit: 1).first\n# Extract their primary email address ID\nemail_id = user[\"primary_email_address_id\"]\n\n# Create an organization\np Clerk::SDK.organizations.create_organization({\n  create_organization_request: ClerkHttpClient::CreateOrganizationRequest.new({\n    name: 'example'\n  })\n})\n```\n\n## Configuration\n\nThe SDK can be configured in three ways: environment variables, configuration\nsingleton and constructor arguments. The priority goes like this:\n\n1. Constructor arguments\n2. Configuration object\n3. Environment variables\n\nIf an argument is not provided, the configuration object is looked up, which\nfalls back to the associated environment variable. Here's an example with all\nsupported configuration settings their environment variable equivalents:\n\n```ruby\nClerk.configure do |c|\n  c.secret_key = \"sk_(test|live)_....\" # if omitted: ENV[\"CLERK_SECRET_KEY\"] - API calls will fail if unset\n  c.publishable_key = \"pk_(test|live)_....\" # if omitted: ENV[\"CLERK_PUBLISHABLE_KEY\"] - Handshake mechanism (check section below) will fail if unset\n  c.logger = Logger.new(STDOUT) # if omitted, no logging\n  c.middleware_cache_store = ActiveSupport::Cache::FileStore.new(\"/tmp/clerk_middleware_cache\") # if omitted: no caching\n  c.excluded_routes [\"/foo\", \"/bar/*\"]\nend\n```\n\nYou can customize each instance of the `Clerk::SDK` object by passing keyword\narguments to the constructor:\n\n```ruby\nclerk = Clerk::SDK.new(\n    logger: Logger.new()\n    secret_key: \"X\",\n)\n```\n\nFor full customization, you can instead pass a `Faraday` object directly, which\nwill ignore all the other arguments, if passed:\n\n```ruby\nfaraday = Faraday.new()\nclerk = Clerk::SDK.new(connection: faraday)\n```\n\nRefer to the [Faraday documentation](https://lostisland.github.io/faraday/usage/#customizing-faradayconnection)\nfor details.\n\n## Rack middleware\n\nThe SDK comes with a Rack middleware which lazily loads the Clerk session and\nuser. It inserts a `clerk` key in the Rack environment, which is an instance\nof `Clerk::Proxy`. To get the session or the user of the session, you call\n`session` or `user` respectively. In case there is no session, you can retrieve\nthe API error with the `error` getter method.\n\n```ruby\nuse Clerk::Rack::Middleware\n```\n\n### Reverification middleware\n\nThe SDK comes with a revalidation middleware which will automatically revalidate the session when the user navigates to a protected route.\n\n```ruby\nuse Clerk::Rack::Reverification,\n  preset: Clerk::StepUp::Preset::LAX,\n  routes: [\"/*\"]\n```\n\n\n\n## Rails integration\n\nThe SDK will automatically add the [Rack middleware](#rack-middleware) to the\nmiddleware stack. For easier access to the Clerk session and user, include the\n`Clerk::Authenticatable` concern in your controller:\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  include Clerk::Authenticatable\nend\n\nclass AdminController \u003c ApplicationController\n  before_action :require_reverification!, only: [:protected]\n\n  def index\n    @user = clerk.user\n  end\n\n  def protected\n    render json: {message: clerk.user? ? \"Valid session\" : \"Not logged in\"}\n  end\nend\n```\n\nThis gives your controller and views access to the following methods and more:\n\n- `clerk.sdk.*`\n- `clerk.user?`\n- `clerk.user`: NOTE: This makes an additional request and attempts to cache it.\n- `clerk.user_id`\n- `clerk.organization?`\n- `clerk.organization` NOTE: This makes an additional request and attempts to cache it.\n- `clerk.organization_id`\n- `clerk.organization_role`\n- `clerk.organization_permissions`\n\n### Skipping the Railtie\n\nThere are cases where you might not want to use the Railtie, for example, only using the SDK in a Rails application. To accomplish this, you can set the `CLERK_SKIP_RAILTIE` environment variable to `true`.\n\nThis will prevent the Railtie from being loaded and the Rack middleware from being added to the middleware stack.\n\nYou can still configure the SDK as normal, but you will need to call the SDK using `Clerk::SDK.new` instead of the `clerk.sdk` helper.\n\n## Sinatra integration\n\nThe SDK enables the use of Extensions to add Clerk support to your Sinatra application.\n\n`Sinatra::Clerk` will automatically add the [Rack middleware](#rack-middleware)to the\nmiddleware stack and enable easy access to the Clerk session and user helper methods.\n\n```ruby\nclass App \u003c Sinatra::Base\n  register Sinatra::Clerk\n\n  get \"/\" do\n    erb :index, format: :html5\n  end\n\n  get \"/admin\" do\n    @user = clerk.user\n    erb :index, format: :html5\n  end\n\n  get \"/protected\" do\n    require_reverification!\n    {message: clerk.user? ? \"Valid session\" : \"Not logged in\"}.to_json\n  end\nend\n```\n\n## Internals\n\nThe API client depends on the excellent [Faraday](https://rubygems.org/gems/faraday)\ngem for HTTP requests. You can swap out the original implementation with your\nown customized instance.\n\nThe API client sends all requests as `application/x-www-form-urlencoded`. The\nAPI then responds with JSON which is then converted and returned as a Ruby\n`Hash`, or `Array` of hashes. Errors are also returned as a JSON object, with a\nsingle key (`errors`) containing an array of error objects.\n\nRead the [API documentation](https://clerk.com/docs/reference/backend-api)\nfor details on expected parameters and response formats.\n\n\u003ca name=\"handshake\"\u003e\u003c/a\u003e\n\n### Handshake\n\nThe 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.\n\nWith 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.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`bundle exec rake spec` to run the tests. You can also run `bin/console` for an\ninteractive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. \n\nTo run the example applications, run:\n\n```bash\nrake app:rack    \nrake app:rails  \nrake app:rails:api\nrake app:sinatra\n```\n\n## Release\n\nTo release a new version:\n- update the version number in `version.rb`\n- update `CHANGELOG.md` to include information about the changes\n- merge changes into main\n- run `bundle exec rake release`\n\nIf gem publishing is NOT executed automatically:\n- run `gem push pkg/clerk-sdk-ruby-{version}.gem` to push the `.gem` file to [rubygems.org](https://rubygems.org)\n\nThe `bundle exec rake release` command:\n- creates a git tag with the version found in `version.rb`\n- pushes the git tag\n\n## Yank release\n\nWe should avoid yanking a releasing but if it's necessary execute `gem yank clerk-sdk-ruby -v {version}`\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/clerkinc/clerk-sdk-ruby.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclerk%2Fclerk-sdk-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclerk%2Fclerk-sdk-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclerk%2Fclerk-sdk-ruby/lists"}