Auth0 Ruby SDK

Network Access Control Lists (ACLs) allow you to manage access control entries for your client. You can list, create, get, update, set, or delete these entries.

Common Parameters for ACL operations:

• description: String. A description of the ACL.
• active: Boolean. Whether the ACL is actively being used.
• priority: Integer. The evaluation order relative to other rules.
• rule: Auth0::Types::NetworkACLRule. The rule definition containing action and scope (e.g., scope: "management").

v6 has moved away from positional arguments and mixed option hashes. All methods now use keyword arguments exclusively.

Example Migration:

# v5 (Positional/Mixed)
client.create_user('ConnName', email: 'user@example.com')
client.user('id', fields: 'email')

# v6 (All Keyword Arguments)
client.users.create(connection: 'ConnName', email: 'user@example.com')
client.users.get(id: 'id', fields: 'email')

# v6 pattern
client.users.create(
  connection: 'Username-Password-Authentication',
  email: 'user@example.com',
  password: 'Pass123!'
)

Version 6 introduces a sub-client pattern for all Management API resources. Instead of calling methods directly on the client object, you must access the resource sub-client first.

Common transformations include:

• List/Get: client.users(opts) $\rightarrow$ client.users.list(**opts); client.user(id) $\rightarrow$ client.users.get(id: id)
• Create/Update/Delete: client.create_user(...) $\rightarrow$ client.users.create(...); client.patch_user(id, body) $\rightarrow$ client.users.update(id: id, **body)
• Sub-resources: client.get_user_roles(user_id) $\rightarrow$ client.users.roles.list(id: user_id)

Client credentials can be used to configure Private Key JWT, mTLS authentication methods, or JWT-secured Authorization requests.

Important: Creating a credential does not automatically enable it. To use a credential, you must update the client configuration:

• For Private Key JWT or mTLS: Set the client_authentication_methods property on the client.
• For JWT-secured Authorization requests: Set the signed_request_object property on the client.

In v6, management methods are no longer top-level methods on the client. They are accessed through resource-specific sub-clients (e.g., client.users, client.roles, client.organizations).

Comparison:

# v6 pattern
client.users.list(per_page: 10)
client.users.get(id: 'auth0|123')
client.users.create(connection: 'Username-Password-Authentication', email: 'a@b.com')

The SDK provides a unified interface by combining two distinct API clients into a single entry point:

1. Management API (Auth0::Management): Auto-generated via Fern. These files reside in lib/auth0/ and should not be edited manually as they are subject to regeneration.
2. Authentication API (Auth0::Api::AuthenticationEndpoints): Hand-written endpoints ported from the original SDK. These are protected from regeneration.
3. Unified Client (Auth0::Client): The primary interface defined in lib/auth0/auth_client.rb. It combines the two APIs using mixins for authentication logic and delegation for management logic.

The Auth0::Client provides a high-level interface to the Management API. When initialized with a client_secret, it can automatically manage tokens. You can access specific resource groups like users, roles, connections, and organizations directly from the client.

Common operations include:

• client.users.list(q: '...', per_page: 50)
• client.users.create(...)
• client.roles.list(...)
• client.organizations.list(...)

You can also access the underlying Auth0::Management instance directly via client.management.

# Example: Listing users with specific fields
@users = auth0_client.users.list(
  q: "email:*auth0*",
  fields: "email,user_id,name",
  include_fields: true,
  page: 0,
  per_page: 50
)

# Example: Accessing management directly
management = client.management
management.users.list(per_page: 5)

The Authentication API is not affected by the v6 major version change. Any code written for the Authentication API in v5 will work in v6 without modification. This includes methods such as:

• signup
• authorization_url
• login
• obtain_user_tokens
• change_password
• logout_url
• validate_id_token

Use the following commands to run the test suites and linting tools:

• Run all tests: Executes the full test suite.
• Run unit tests: Executes only the unit tests.
• Run RuboCop: Runs the Ruby style guide linter.

# Run all tests
bundle exec rake test

# Run only unit tests
bundle exec rake spec

# Run rubocop
bundle exec rubocop

To develop with this SDK, ensure you have the correct Ruby version installed (refer to the .ruby-version file in the repository).

First, install the necessary dependencies using Bundler:

bundle install