Ruby Client Library
On this page
The Ruby client library integrates FusionAuth with your Ruby application. The source code is in the Ruby client GitHub repository.
Install#
Install the fusionauth_client gem:
gem install fusionauth_client
Register a User#
The following examples assume FusionAuth runs at http://localhost:9011. Each example contains an API key. Replace the API key with your own. When FusionAuth doesn't run locally, replace the host URL too.
The following example uses the register method to create a User and a Registration:
require 'fusionauth/fusionauth_client'
require 'securerandom'
require 'pp'
# Construct the FusionAuth Client
client = FusionAuth::FusionAuthClient.new(
'REPLACE_ME',
'http://localhost:9011'
)
application_id = '85a03867-dccf-4882-adde-1a79aeec50df'
# Create a user + registration
id = SecureRandom.uuid
response = client.register(id, {
user: {
firstName: 'Ruby',
lastName: 'User',
email: 'ruby_user@example.com',
password: 'password'
},
registration: {
applicationId: application_id,
data: {
foo: 'bar'
},
preferredLanguages: %w(en fr),
roles: %w(dev)
}
})
if response.success_response
pp response.success_response
else
if response.exception
# no connection
print response.exception
end
print "status: #{response.status}"
print response.error_response
exit
end
Usage Suggestions#
Choose a Use Case#
Client libraries wrap the REST API. You can use a client library for two tasks.
The main task is calling the FusionAuth APIs from code. You get auto-completion and typed objects, which helps when you script configuration, automate common tasks, or copy existing Applications and Groups. The API documentation lists the JSON structure of every request and which fields each call requires. When you need the details, read the API documentation and the library source code.
The secondary task is exchanging an authorization code for tokens in the Authorization Code grant. For this task, use an OAuth library for your language instead. For a list of libraries, see the community curated list.
Client libraries don't provide higher level functionality such as token management. To request that functionality, comment on or upvote the open issue.
When a client library doesn't fit your needs, call the REST API directly.
Requests and Responses#
Each library maps a request object to the JSON that the matching API method requires. Depending on the API call, the request object is a set of string parameters or a complex object. When you use a language without static typing, read the API documentation for the operation to learn the expected fields.
Each library returns a response object with these fields:
- A status that matches the HTTP status code from the API. The status is
-1when no HTTP request succeeded. - A JSON success object when the call succeeds.
- A JSON error object with a message when the status is
4xxor5xx. - An exception object when the library sent no request or the server returned no usable response.
Use Separate Clients for API Key Scopes#
When a script calls endpoints with different API key scopes, create one client instance per scope. For example, Entities accept a tenant-scoped API key, but Entity Types and Lambdas require a global API key.
Follow these rules when your library lets you set a Tenant Id on the client instance:
- Set the Tenant Id on the tenant-scoped client only.
- Don't change the Tenant Id on a shared client between calls.
- Don't send a tenant header to a global-only endpoint. The endpoint fails with a
401.
Example Apps#
- Ebook application - Example Rails app which lets you download ebooks
- Lob integration - Example Rails app which lets send a letter to someone's address to verify they live there
- Migrating from Rails example - Example of migrating from Rails-based authentication
- Ruby JWT - JWT creation and decoding examples with the Ruby jwt gem
- Ruby on Rails API quickstart - Ruby on Rails API quickstart tutorial showing how to integrate FusionAuth with a Ruby on Rails API
- Ruby on Rails quickstart - Ruby on Rails quickstart tutorial showing how to integrate FusionAuth with a Ruby on Rails application
- Ruby on Rails with Custom Scopes - This example application shows how to implement Custom Scopes with FusionAuth.
- Ruby tenant creation - Creating new tenants in Ruby
Update Policy#
FusionAuth releases new versions of the SDKs and client libraries to track the FusionAuth API. SDKs and client libraries may also receive bug fixes, security patches, tests, code samples, and documentation changes.
These releases may update dependencies, language engines, and operating systems, because FusionAuth follows the deprecation and sunsetting policies of the underlying technologies. When the maintainer deprecates a language, framework, or operating system, FusionAuth deprecates the SDKs and client libraries that depend on the technology. FusionAuth then updates the SDKs and client libraries to use a newer version.
For more information, see Update a Client Library.