auth0 5.18.1 → 6.0.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9f09b3cbb82970d76ce07a4e20b7791059f9e6c8874e8c7723b9e02fa2f7221
-  data.tar.gz: ac5451e6f51c813f40ad9f233253a9d3556e7aa4a1908aec8d6ed95b3a1a99a9
+  metadata.gz: cfc6da350a9f7730aaf8f038703f0343e07b137e1feddf2e9d63e2b517ab2774
+  data.tar.gz: 6f23751f66ee9bff02ee3baacafff7038f6e9774a2e1ec765f15cef9b26f61ce
 SHA512:
-  metadata.gz: fdaf8bf8869532464bd71f51fbba1503e1d529d9fd06e35a9d88dc346400858a60c4b0de7a85b2a079f45fec342e62fca3042c8872ad3cdd48efa6d27dba1f04
-  data.tar.gz: f43c6fc7a97a0ff55acd7b92f7f6376a52877f3988219b102c8c69625e753ca7540f50be464771f137b4e45e577a4665ee44f87e493c3f814d7d1e74636f1d00
+  metadata.gz: 9f853014893b8025307a7bb3a9cd44b08e2a2b2504d1a5b91d3380cfa00e7783de34574d72ece69087f975e22fd97ba829e734cd2dc65a270eb2a3408600ad9f
+  data.tar.gz: 3a3ce1a28ac083e94939d503c000b74edca056237d916c866fa4e133a59af29a98f688f06a9a1c647aace69db39f44a7821ed17bd50e8b722f7ed6fc655876b2

data/.fernignore

@@ -0,0 +1,29 @@
+# Specify files that shouldn't be modified by Fern
+changelog.md
+lib/auth0/client.rb
+lib/auth0/auth_client.rb
+lib/auth0/exception.rb
+lib/auth0/algorithm.rb
+lib/auth0/client_assertion.rb
+lib/auth0/mixins.rb
+lib/auth0/mixins/
+lib/auth0/api/
+lib/auth0_client.rb
+custom.gemspec.rb
+
+# Telemetry customization
+lib/auth0/internal/http/raw_client.rb
+test/unit/authentication_endpoints_test.rb
+
+.rubocop.yml
+
+# Documentation
+README.md
+EXAMPLES.md
+DEVELOPMENT.md
+DEPLOYMENT.md
+CODE_OF_CONDUCT.md
+RUBYGEM.md
+v6_MIGRATION_GUIDE.md
+.github/PULL_REQUEST_TEMPLATE.md
+examples/

data/.rubocop.yml

@@ -1,10 +1,88 @@
-inherit_from: .rubocop_todo.yml
-require:
-  - rubocop-rails
-Rails:
-  Enabled: true
+plugins:
+  - rubocop-minitest
+
 AllCops:
- Exclude:
-   - bin/**/*
-   - vendor/**/*
-   - auth0.gemspec
+  TargetRubyVersion: 3.3
+  NewCops: enable
+  # Files ported verbatim from the legacy ruby-auth0 SDK (authentication API).
+  # Excluded to preserve exact compatibility with the original source.
+  Exclude:
+    - "examples/**/*"
+    - "lib/auth0/exception.rb"
+    - "lib/auth0/mixins/access_token_struct.rb"
+    - "lib/auth0/mixins/api_token_struct.rb"
+    - "lib/auth0/mixins/permission_struct.rb"
+    - "lib/auth0/client_assertion.rb"
+    - "lib/auth0/mixins/headers.rb"
+    - "lib/auth0/mixins/httpproxy.rb"
+    - "lib/auth0/mixins/token_management.rb"
+    - "lib/auth0/mixins/validation.rb"
+    - "lib/auth0/algorithm.rb"
+    - "lib/auth0/api/authentication_endpoints.rb"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Naming/VariableNumber:
+  EnforcedStyle: normalcase
+
+Style/Documentation:
+  Enabled: false
+
+Style/OneClassPerFile:
+  Exclude:
+    - "test/**/*"
+
+Style/Lambda:
+  EnforcedStyle: literal
+
+Minitest/MultipleAssertions:
+  Enabled: false
+
+Minitest/UselessAssertion:
+  Enabled: false
+
+# Dynamic snippets are code samples for documentation, not standalone Ruby files.
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - "dynamic-snippets/**/*"
+
+Layout/FirstHashElementIndentation:
+  Exclude:
+    - "dynamic-snippets/**/*"

data/.version

@@ -1 +1 @@
-v5.18.1
+v6.0.0.beta.0

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Change Log
 
+## 6.0.0-beta.0 (2026-04-30)
+
+[Full Changelog](https://github.com/auth0/ruby-auth0/compare/v5.18.1...v6.0.0.beta.0)
+
+This beta release completely rewrites the Management API client using [Fern](https://buildwithfern.com/) code generation from the Auth0 OpenAPI specification. The Authentication API is ported from v5 and maintains full feature parity.
+
+**Breaking Changes**
+- Management API client rewritten using Fern code generation
+- `Auth0Client` replaced by `Auth0::Client` (unified client for Auth + Management APIs)
+- Management API methods accessed via namespaced sub-clients (`client.users.list` instead of `client.users`)
+- API methods return strongly-typed response objects instead of raw hashes
+- List methods return paginated iterators instead of arrays
+- Non-2xx responses raise typed exceptions (`Auth0::Errors::NotFoundError`, etc.) instead of returning error hashes
+- `rest-client` dependency removed; uses `net/http` internally
+- Minimum Ruby version raised to 3.3
+
+**Added**
+- Auto-generated Management API with complete endpoint coverage from Auth0 OpenAPI spec
+- Automatic OAuth 2.0 client credentials token management
+- Built-in retry with exponential backoff for rate-limited (429) responses
+- Configurable timeouts per request via `request_options`
+- Offset-based pagination with `each` iterators for all list endpoints
+- Telemetry headers on Management API requests
+- Wire tests (WireMock-based) for all Management API endpoints
+- New examples (Sinatra API and Rails 7 API)
+- `v6_MIGRATION_GUIDE.md` for upgrading from v5
+
+**Unchanged**
+- Authentication API (login, signup, token exchange, passwordless, MFA) — ported from v5 with identical interface
+
 ## [v5.18.1](https://github.com/auth0/ruby-auth0/tree/v5.18.1) (2026-03-13)
 [Full Changelog](https://github.com/auth0/ruby-auth0/compare/v5.18.0...v5.18.1)
 

data/DEPLOYMENT.md

@@ -4,58 +4,50 @@
 
 Make sure you have access in https://rubygems.org/gems/auth0/ and that your Ruby Gems tokens are set in `~/.gem/credentials`.
 
-In order to generate the required changelog entry, define an environment variable `GITHUB_READ_TOKEN` with a Github API token that has READ access to `repo:public_repo`. You can generate a Github API Token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token).
-
-Create a new Github Milestone with the version name prefixed with `v`. i.e. `v4.10.2`. Assign every Issue and Pull Request to be included on this release to that Milestone, and tag them with the `CH:xxxxxx` labels, depending on the type of change fixed or introduced there.
-
-Finally, follow the next steps:
+## Release process
 
 ```bash
-# Install gems for exec commands
+# Install gems
 bundle install
 
 # Run all tests
 bundle exec rake test
 
 # Create a release branch
-git checkout master
+git checkout main
 git pull
 git checkout -b release-X.X.X
 git push --set-upstream origin release-X.X.X
 
-# Update the version number
-# This will create a commit with the new version
-bundle exec gem bump --version X.X.X
+# Update the version number in lib/auth0/version.rb
+# Commit the version bump
+git commit -am "Bump version to X.X.X"
 
 # Make sure the Gemfile.lock is up-to-date
 bundle update
 git commit -am "Update gems"
 
-# Generate the changelog
-github_changelog_generator -t $GITHUB_READ_TOKEN
-# ... or similar.
-# Review the changelog
-# Remove "unreleased" section
-# Make sure the tags are ordered
-
 # Commit, push, and create a PR for this release
-git commit -am "Update CHANGELOG.md"
 git push
 
-# Add related milestone
 # Create PR on GitHub and assign for review
-# Merge/rebase and delete branch once approved
+# Merge and delete branch once approved
 
 # Create and add a tag
-git checkout master
+git checkout main
 git pull
-bundle exec gem tag
+git tag vX.X.X
 git push origin vX.X.X
-# Create a new release from this tag on GitHub using markdown from the changelog
 
-# Make sure you are an author for this gem here https://rubygems.org/gems/auth0/
-# Rubygems token can be updated in ~/.gem/credentials
-bundle exec gem release
+# Create a new release from this tag on GitHub
+
+# Publish to RubyGems
+# Make sure you are an author for this gem: https://rubygems.org/gems/auth0/
+gem build auth0.gemspec
+gem push auth0-X.X.X.gem
 ```
 
-The steps above were tested with Ruby `v2.5.7`.
+## Notes
+
+- The Management API client is generated by [Fern](https://buildwithfern.com). Run `fern generate` to update it. After regeneration, check for new management resource accessors and update `lib/auth0/auth_client.rb` accordingly.
+- Files listed in `.fernignore` are not overwritten by Fern regeneration.

data/DEVELOPMENT.md

@@ -1,9 +1,17 @@
 # Development
 
-In order to set up the local environment you'd have to have Ruby installed and a few global gems used to run and record the unit tests. A working Ruby version can be taken from the [CI script](/.circleci/config.yml). At the moment of this writting we're using Ruby `2.5.7`.
+In order to set up the local environment you'll need to have Ruby installed. Check the `.ruby-version` file or CI configuration for the recommended Ruby version.
 
 > It is expected that every Pull Request introducing a fix, change or feature contains enough test coverage to assert the new behavior.
 
+## Architecture
+
+This SDK combines a Fern-generated Management API client with a hand-written Authentication API client:
+
+- **Management API** (`Auth0::Management`) - Auto-generated by [Fern](https://buildwithfern.com). Source files live in `lib/auth0/` (except those listed in `.fernignore`). Do not edit generated files directly; changes will be overwritten on regeneration.
+- **Authentication API** (`Auth0::Api::AuthenticationEndpoints`) - Hand-written, ported from the original ruby-auth0 SDK. Source files are listed in `.fernignore` to protect them from Fern regeneration.
+- **Unified Client** (`Auth0::Client`) - Defined in `lib/auth0/auth_client.rb`, combines both APIs via mixins (authentication) and delegation (management).
+
 ## Running the tests
 
 Install the gems required for this project.
@@ -12,7 +20,7 @@ Install the gems required for this project.
 bundle install
 ```
 
-Finally, run the tests.
+Run all tests:
 
 ```bash
 bundle exec rake test
@@ -20,16 +28,31 @@ bundle exec rake test
 
 ### Running only unit tests
 
-You can run only the unit tests and ignore the integration tests by running the following:
-
 ```bash
 bundle exec rake spec
 ```
 
-### Running only integration tests
-
-You can run only the unit tests and ignore the integration tests by running the following:
+### Running rubocop
 
 ```bash
-bundle exec rake integration
+bundle exec rubocop
 ```
+
+Note: Verbatim-ported files from the original SDK are excluded from rubocop checks via `.rubocop.yml`.
+
+## Files protected by .fernignore
+
+The following files are protected from Fern regeneration and can be edited directly:
+
+- `lib/auth0/client.rb` - `Auth0::Management` class (copied from Fern output, with `require_relative "auth_client"` appended)
+- `lib/auth0/auth_client.rb` - `Auth0::Client` unified class
+- `lib/auth0/mixins/` - Authentication infrastructure (initializer, token management, HTTP proxy, etc.)
+- `lib/auth0/api/` - Authentication API endpoints
+- `lib/auth0/exception.rb` - Authentication error classes
+- `lib/auth0/algorithm.rb` - JWT algorithm helpers
+- `lib/auth0/client_assertion.rb` - Client assertion JWT signing
+- `custom.gemspec.rb` - Additional gem dependencies
+- `test/unit/authentication_endpoints_test.rb` - Authentication endpoint tests
+- All documentation files (`README.md`, `EXAMPLES.md`, etc.)
+
+When Fern regenerates the SDK, check for new management resource accessors in the generated `lib/auth0/client.rb` and add them to both `Auth0::Management` and the `MANAGEMENT_ACCESSORS` list in `lib/auth0/auth_client.rb`.

data/EXAMPLES.md

@@ -1,25 +1,24 @@
-# Examples using ruby-auth0
+# Examples
 
 ## Build a URL to Universal Login Page
 
 ```ruby
 require 'auth0'
 
-client = Auth0Client.new(
+client = Auth0::Client.new(
   client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
   client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
   domain: ENV['AUTH0_RUBY_DOMAIN'],
 )
 
-client.authorize_url 'http://localhost:3000'
-
-> => #<URI::HTTPS https://YOUR_DOMAIN/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000>
+client.authorization_url 'http://localhost:3000'
 
+# => #<URI::HTTPS https://YOUR_DOMAIN/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000>
 ```
 
 ## Management API Client
 
-As a simple example of how to get started with the management API, we'll create an admin route to point to a list of all users from Auth0:
+As a simple example of how to get started with the Management API, we'll create an admin route to point to a list of all users from Auth0:
 
 ```ruby
 # config/routes.rb
@@ -39,26 +38,24 @@ require 'auth0'
 class AllUsersController < ApplicationController
   # Get all users from Auth0 with "auth0" in their email.
   def index
-    @params = {
+    @users = auth0_client.users.list(
       q: "email:*auth0*",
-      fields: 'email,user_id,name',
+      fields: "email,user_id,name",
       include_fields: true,
       page: 0,
       per_page: 50
-    }
-    @users = auth0_client.users @params
+    )
   end
 
   private
 
   # Setup the Auth0 API connection.
   def auth0_client
-    @auth0_client ||= Auth0Client.new(
+    @auth0_client ||= Auth0::Client.new(
       client_id: ENV['AUTH0_RUBY_CLIENT_ID'],
       client_secret: ENV['AUTH0_RUBY_CLIENT_SECRET'],
       domain: ENV['AUTH0_RUBY_DOMAIN'],
-      api_version: 2,
-      timeout: 15 # optional, defaults to 10
+      management_timeout: 15 # optional, defaults to 60
     )
   end
 end
@@ -71,11 +68,59 @@ Finally, we'll add a view to display the results:
 ```ruby
 # app/views/all_users/index.html.erb
 <h1>Users</h1>
-<%= debug @params %>
 <%= debug @users %>
 ```
 
-This should show the parameters passed to the `users` method and a list of users that matched the query (or an empty array if none).
+### More Management API examples
+
+```ruby
+# Create a user
+client.users.create(
+  connection: 'Username-Password-Authentication',
+  email: 'newuser@example.com',
+  password: 'SecurePassword123!'
+)
+
+# Get a user by ID
+user = client.users.get(id: 'auth0|123456')
+
+# Update a user
+client.users.update(
+  id: 'auth0|123456',
+  user_metadata: { preferred_language: 'en' }
+)
+
+# Delete a user
+client.users.delete(id: 'auth0|123456')
+
+# List roles
+client.roles.list(per_page: 10)
+
+# Create a role
+client.roles.create(name: 'editor', description: 'Content editor')
+
+# List connections
+client.connections.list(per_page: 10)
+
+# Access the underlying Auth0::Management instance directly
+management = client.management
+management.users.list(per_page: 5)
+```
+
+### Using Auth0::Management directly
+
+If you only need the Management API and already have a token, you can skip `Auth0::Client` entirely:
+
+```ruby
+management = Auth0::Management.new(
+  token: ENV['AUTH0_MANAGEMENT_API_TOKEN'],
+  base_url: 'https://YOUR_DOMAIN.auth0.com/api/v2'
+)
+
+management.users.list(q: 'email:*auth0*', per_page: 10)
+management.roles.create(name: 'admin', description: 'Administrator')
+management.organizations.list(take: 20)
+```
 
 ## Organizations
 
@@ -90,7 +135,7 @@ Configure the Authentication API client and pass your Organization ID or name to
 ```ruby
 require 'auth0'
 
-@auth0_client ||= Auth0Client.new(
+@auth0_client ||= Auth0::Client.new(
   client_id: '{YOUR_APPLICATION_CLIENT_ID}',
   client_secret: '{YOUR_APPLICATION_CLIENT_SECRET}',
   domain: '{YOUR_TENANT}.auth0.com',
@@ -109,7 +154,7 @@ Auth0 Organizations allow users to be invited using emailed links, which will di
 ```ruby
 require 'auth0'
 
-@auth0_client ||= Auth0Client.new(
+@auth0_client ||= Auth0::Client.new(
   client_id: '{YOUR_APPLICATION_CLIENT_ID}',
   client_secret: '{YOUR_APPLICATION_CLIENT_ID}',
   domain: '{YOUR_TENANT}.auth0.com',
@@ -124,6 +169,34 @@ universal_login_url = @auth0_client.authorization_url("https://{YOUR_APPLICATION
 # redirect_to universal_login_url
 ```
 
+### Managing Organizations via Management API
+
+```ruby
+# List organizations
+client.organizations.list(take: 50)
+
+# Create an organization
+org = client.organizations.create(
+  name: 'acme-corp',
+  display_name: 'Acme Corporation'
+)
+
+# Get an organization by name
+org = client.organizations.get_by_name(name: 'acme-corp')
+
+# Add members to an organization
+client.organizations.members.create(
+  id: org[:id],
+  members: ['auth0|user_id_1', 'auth0|user_id_2']
+)
+
+# List organization members
+client.organizations.members.list(id: org[:id], take: 50)
+
+# Delete an organization
+client.organizations.delete(id: org[:id])
+```
+
 ## ID Token Validation
 
 An ID token may be present in the credentials received after authentication. This token contains information associated with the user that has just logged in, provided the scope used contained `openid`. You can [read more about ID tokens here](https://auth0.com/docs/tokens/concepts/id-tokens).
@@ -172,7 +245,7 @@ end
 
 ### Organization claim validation
 
-If an `org_id` or `org_name` claim is present in the access   token, then the claim should be validated by the API to ensure that the value received is expected or known.
+If an `org_id` or `org_name` claim is present in the access token, then the claim should be validated by the API to ensure that the value received is expected or known.
 
 In particular:
 
@@ -208,7 +281,7 @@ Specify the client assertion key when creating the Auth0 client as in the follow
 key_string = File.read 'key.pem'
 key = OpenSSL::PKey::RSA.new key_string
 
-client = Auth0Client.new(
+client = Auth0::Client.new(
   domain: 'AUTH0_DOMAIN',
   client_id: 'AUTH0_CLIENT_ID',
   client_assertion_signing_key: key,
@@ -220,3 +293,20 @@ Some notes:
 * If both `client_secret` and `client_assertion_signing_key` are specified, `client_assertion_signing_key` takes precedence
 * `client_assertion_signing_alg` is optional and defaults to `RS256` if omitted
 * Only `RS256`, `RS384` and `PS256` algorithms are supported by Auth0 currently
+
+## Custom token provider
+
+If you have your own mechanism for obtaining Management API tokens, you can provide a custom token provider:
+
+```ruby
+client = Auth0::Client.new(
+  domain: ENV['AUTH0_RUBY_DOMAIN'],
+  token_provider: -> {
+    # Fetch a token from your vault, cache, or other source
+    MyVault.get_auth0_token
+  }
+)
+
+# The token provider will be called whenever a new token is needed
+client.users.list(per_page: 10)
+```