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 -1 when no HTTP request succeeded.
  • A JSON success object when the call succeeds.
  • A JSON error object with a message when the status is 4xx or 5xx.
  • 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#

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.