View Source Changelog

2.5.1

This is a maintenance release. The library code (lib/) is unchanged from 2.5.0; only the documentation and the test suite change.

Changed

  • 📝 Remove the internal Management API diff inventory (docs/management_api_diff.md) from the ExDoc documentation, and drop the links to it from README and this changelog.
  • 📝 Render the internal modules mentioned in README and this changelog (Auth0.Application, Auth0.Authentication.Token.ClientCredentials.Params, Auth0.Entity.Token) as plain inline code instead of links to hidden modules, so mix docs builds without warnings.

Fixed

  • ✅ Fix the 4 connect-timeout tests in test/auth0/common/http_options_test.exs that failed during setup on macOS: the test server now listens with a backlog of 1 instead of 0, which macOS treated as its default of 128.

2.5.0

This release brings the library up to date with the official Auth0 Management API v2 OpenAPI specification (fetched 2026-09-24). It adds the missing endpoints and parameters, fixes functions that did not match the specification, and deprecates functions whose endpoints were removed or reached end of life. No public function or arity is removed. The requirements are unchanged from 2.4.0 (Elixir 1.17+, Erlang/OTP 27+).

A few return values change as bug fixes (see "Fixed"). Calling a deprecated function now emits a compile-time warning, so read "Deprecated" if you compile with --warnings-as-errors.

Added

  • ✨ 153 new functions in Auth0.Api.Management: 148 for endpoints that were not supported, and 5 that expose endpoints that 2.4.0 only had internally (get_attack_protection_bot_detection, update_attack_protection_bot_detection, get_prompt_rendering, update_prompt_rendering, update_session). By area:
    • Actions: action modules (list, create, get, update, delete, the actions using a module, rollback, versions) — get_action_modules, create_action_module, …
    • Agents (new facade Auth0.Management.Agents): list, create, get, update, delete
    • Attack Protection: CAPTCHA and phone provider protection settings (get / update)
    • Client Grants: get a client grant, list its organizations
    • Clients: CIMD metadata preview and client registration, list the connections of a client
    • Connection Profiles: create, delete, templates (list / get)
    • Connections: enabled clients (get_connection_clients, update_connection_clients), directory provisioning (configuration, default mapping, synchronizations, synchronized groups), connection keys (list / create / rotate), tenant-wide listings of directory provisionings and SCIM configurations
    • Custom Domains: default custom domain (get / set), test a custom domain
    • Emails: delete the email provider
    • Event Streams: deliveries (list / get), redelivery, test event
    • Flows / Forms: Flows vault connections (CRUD), flow executions (list / get / delete), delete a flow, delete a form
    • Groups (new facade Auth0.Management.Groups): list, get, delete, members, roles (list / assign / remove)
    • Guardian: Duo, email and phone factor settings, Guardian settings
    • Keys: custom signing keys (get / set / delete), Network ACL keys (list / create / get / delete)
    • Network ACLs: replace a Network ACL (set_network_acl)
    • Organizations: search, client grants, clients, associated connections (/organizations/{id}/connections; named *_organization_associated_connection* to keep them apart from the existing *_organization_connection* functions for enabled connections), discovery domains, members' effective roles, role members, groups and their roles
    • Prompts: rendering settings for all screens (list / bulk update)
    • Rate Limit Policies (new facade Auth0.Management.RateLimitPolicies): list, create, get, update, delete
    • Refresh Tokens: list, update, revoke (revoke_refresh_tokens)
    • Resource Servers: search
    • Risk Assessments: settings and new-device settings (get / update), clear a user's risk assessments (clear_user_risk_assessments)
    • Roles: groups (list / assign / remove)
    • Self-Service Profiles: custom text (get / set), revoke an SSO ticket
    • Supplemental Signals: configuration (get / update)
    • User Attribute Profiles: templates (list / get)
    • Users: connected accounts, effective permissions and roles (and their sources), groups
  • ✨ 44 of the new functions are for Early Access endpoints; their @doc says so. The Experimentation endpoints (beta, apart from one Early Access endpoint that depends on them), GET /clients/search (beta), the server-sent events endpoint GET /events, and the deprecated or superseded Guardian SMS endpoints are not added (see the diff list for the reasons).
  • ✨ :custom_domain option for the 9 functions whose endpoints accept the auth0-custom-domain header: create_user, update_user, create_email_verification_ticket, create_password_change_ticket, send_job_verification_email, create_organization_invitation, create_guardian_enrollment_ticket, create_self_service_profile_sso_ticket and test_branding_phone_template. Pass it as a new last argument, e.g. create_user(params, config, custom_domain: "login.example.com"). The existing arities are unchanged and send no header. Only a host name, optionally with a port, is accepted; any other value (including one containing CR/LF) raises ArgumentError, so the option cannot be used to inject headers.
  • ✨ Query parameters with multiple values: passing a list as a query value sends the key once per value (strategy=a&strategy=b), as the specification defines for array parameters (for example strategy of get_connections, hydrate of get_flows / get_flow / get_forms / get_form, identifiers of get_resource_servers). Before, a list raised ArgumentError; scalar values are sent exactly as before, and nil values in a list are skipped.
  • ✨ get_custom_domain_configurations and get_daily_stats accept query parameters (get_custom_domain_configurations(params, config), get_daily_stats(%{from: ..., to: ...}, config)). Calls that pass only a config behave as before.
  • 📝 The @doc of existing functions lists their query parameters (marking required, array and Early Access ones), and notes Early Access / beta / deprecated body properties.
  • ✨ Two public helpers in Auth0.Common.Util for building request paths:
    • encode_path_param/1 percent-encodes a path parameter value (every character except A-Z a-z 0-9 - . _ ~; a value of . or .. is encoded too), e.g. encode_path_param("auth0|123") returns "auth0%7C123".
    • build_path/2 builds a request path from an endpoint template and a keyword list of path parameters, encoding each value with encode_path_param/1, e.g. build_path("/api/v2/users/{id}", id: "auth0|123") returns "/api/v2/users/auth0%7C123".
    • The functions for the newly supported endpoints build their paths with them (see "Path parameters").
  • 🔧 Add credo and dialyxir as dev/test dependencies and fix their findings in the existing code (mix credo and mix dialyzer report no issues). They are not runtime dependencies.

Path parameters

  • 🔒 The 148 functions for the newly supported endpoints percent-encode path parameters (every character except A-Z a-z 0-9 - . _ ~; a value of . or .. is encoded too), so an ID such as auth0|123 is sent as auth0%7C123 and a value can never change the requested path. Pass IDs as they are, without encoding them.
  • All other functions (the functions that existed before 2.5.0, including the ones fixed in this release, and the 5 new functions above for endpoints that were already supported internally) still insert path parameters as given, without encoding, so that callers who already pass encoded IDs keep working. If an ID can contain characters such as |, /, ? or #, encode it yourself for these functions. Encoding them all consistently is planned for the next major version.

Deprecated

  • ⚠️ 20 functions of Auth0.Api.Management are marked with @deprecated, and their @doc names the replacement. They still work and are not removed in 2.x.
    • Hooks (end of life announced by Auth0; migrate to Actions): get_hooks → get_actions, create_hook → create_action (then deploy_action and update_action_trigger_bindings), get_hook → get_action, update_hook → update_action, delete_hook → delete_action, get_hook_secrets / add_hook_secrets / update_hook_secrets / delete_hook_secrets → the secrets of an action (get_action / update_action)
    • Rules (end of life announced by Auth0; migrate to Actions): get_rules → get_actions, create_rule → create_action (then deploy_action and update_action_trigger_bindings), get_rule → get_action, update_rule → update_action, delete_rule → delete_action
    • Blacklists (removed from the Management API): get_blacklisted_tokens, blacklist_token. There is no direct replacement; revoke credentials with the purpose-specific functions such as revoke_refresh_tokens or revoke_session.
    • Risk Assessments (these endpoints do not exist in the Management API): create_risk_assessment → get_risk_assessments_settings / update_risk_assessments_settings, the new-device settings functions and clear_user_risk_assessments; get_risk_assessment → get_risk_assessments_settings / get_risk_assessments_new_device_settings
    • Supplemental Signals (these endpoints do not exist in the Management API): create_supplemental_signal → update_supplemental_signals; get_supplemental_signal → get_supplemental_signals
  • ⚠️ Calling any of these functions now produces a compile-time deprecation warning. If you compile with --warnings-as-errors, your build fails until you migrate these calls (or stop treating warnings as errors).
  • ⚠️ In the facade modules, the deprecation is documented only (no @deprecated): in the module documentation of Auth0.Management.Hooks, Auth0.Management.Rules and Auth0.Management.Blacklist, and in the documentation of the affected functions of Auth0.Management.RiskAssessments and Auth0.Management.SupplementalSignals. The @deprecated at the top of hooks.ex / rules.ex in earlier versions only applied to Auth0.Management.Hooks.list/2 / Auth0.Management.Rules.list/2, not to the whole module; it has been removed in favour of the Auth0.Api.Management functions above, so calling those two facade functions directly no longer warns.
  • ⚠️ Deprecated parameters are noted in the @doc of the functions that use them (the functions themselves are not deprecated):
    • enabled_clients of connections (create_connection, update_connection, get_connection) → use get_connection_clients / update_connection_clients
    • deprecated connection options (Facebook, SMS, SAML cert) and deprecated strategies (ip, instagram, oauth1, office365, sharepoint, soundcloud, untappd) (create_connection, update_connection, get_connection, get_connections)
    • oidc_backchannel_logout of clients (create_client, update_client) → use oidc_logout
    • include_totals of get_log_events

Removed

  • 🔥 Remove four unused internal modules that had no documentation (@moduledoc false) and were never called: Auth0.Management.Connections.Status.Check and Auth0.Management.Guardian.AwsSns.Configuration.{Get,Patch,Put} (duplicates of Auth0.Management.Guardian.Factors.PushNotification.Providers.Sns.{Get,Patch,Put}). They were not part of the public API; get_connection_status and get_guardian_aws_sns_configuration / patch_guardian_aws_sns_configuration / update_guardian_aws_sns_configuration are unchanged.

Fixed

  • 🐛 delete_organization_invitation returned {:ok, 204, ""} on success because the success status was never matched. It now returns {:ok, ""}, like the other delete functions that return no body, and as its @spec says. If you match on {:ok, 204, _}, update that code.

  • 🐛 get_connection_status raised on success (it decoded the empty 200 response body). It now returns {:ok, true} when the connection is online, as its @spec ({:ok, boolean}) promised; errors such as 404 (connection not found) are still returned as {:error, status, body}, not as {:ok, false}. The @spec is now {:ok, true} | error.

  • 🐛 get_active_users_count: the @spec said {:ok, integer}, but the function returns the response body as a string (for example {:ok, "123"}). The return value is unchanged; the @spec and @doc are corrected to {:ok, String.t()}.
  • 🐛 update_hook_secrets sent PATCH /api/v2/hooks/{id} (updating the hook itself) instead of PATCH /api/v2/hooks/{id}/secrets.
  • 🐛 rekey_encryption_key sent POST /api/v2/keys/encryption (creating a key) instead of POST /api/v2/keys/encryption/rekey, and its body could not be encoded.
  • 🐛 revoke_session used DELETE instead of POST /api/v2/sessions/{id}/revoke.
  • 🐛 The Verifiable Credentials functions (get_verifiable_credentials, create_verifiable_credential, get_verifiable_credential, update_verifiable_credential, delete_verifiable_credential) sent requests to /api/v2/verifiable-credentials, which does not exist. They now use /api/v2/verifiable-credentials/verification/templates, i.e. they manage verification templates. The function names are kept.
  • 🐛 delete_branding_phone_provider, delete_branding_phone_template, delete_self_service_profile and get_job_error raised on a 204 response (they decoded the empty body). They now return {:ok, ""}.
  • 🐛 add_hook_secrets, create_network_acl and update_token_exchange_profile raised when the success response had no body. They now return {:ok, ""} in that case, and the decoded body as before when there is one.
  • 🐛 create_encryption_wrapping_key always raised Protocol.UndefinedError because its request body could not be encoded.
  • 📝 Correct the 2.3.0 entries: the "Verifiable Credentials" endpoints added in 2.3.0 did not work (see above), and the Risk Assessments and Supplemental Signals functions added in 2.3.0 call endpoints that do not exist in the Management API. They are deprecated in this release, and the endpoints that do exist are added (see "Added").
  • 📝 Fix the ## see links of the Bot Detection functions and of update_hook_secrets.

2.4.0

This release is a security-focused release. It is a minor (not patch) release because it moves to new major versions of the HTTP dependencies and raises the minimum Elixir / Erlang/OTP versions. Read "Breaking changes" before upgrading.

Security

  • 🔒 Remove a leftover IO.inspect/1 in Auth0.Common.Management.Http.multipart_post/3 that printed responses to standard output. No debug output remains under lib/.
  • 🔒 Mask sensitive values in inspect/2 output, and therefore in logs and crash reports that inspect these structs:
    • Auth0.Config: :api_token, :client_secret
    • Auth0.Authentication.Token.ClientCredentials.Params: :client_secret
    • Auth0.Entity.Token: :access_token, :refresh_token, :id_token
    • The fields can still be read from the struct. Masking does not apply to inspect(value, structs: false) or to maps built with Map.from_struct/1.
  • 🔒 Fix the token cache so that a cached Management API token is only returned for the same tenant and credentials. The cache key was the client_id only; it is now {domain, client_id, SHA-256 digest of client_secret}.
    • The same client_id used against different domains (tenants) no longer shares a token.
    • A config with the right domain / client_id but a different client_secret no longer gets a token cached by another caller; it asks /oauth/token itself.
    • The plain client_secret is never stored in the cache (only its digest and the access token are).
  • 🐛 The token cache ETS table is now owned by a supervised process started by Auth0.Application, and all writes go through it. Before, the table was owned by whichever process first requested a token, so the cache was lost when that process exited and other processes could not update it.
  • 🔒 http_protocol is validated. Only "https" (default) and "http" are accepted; "http" is for tests and local mock servers only, because the API token, the client secret and access tokens are sent in plain text. When "http" is used with a non-loopback domain (anything other than localhost, 127.0.0.0/8 or ::1), a warning is logged once per domain. See "HTTP protocol" in the README.
  • 🔒 Fix known hackney advisories that affected 2.3.0 by moving to httpoison 3.0 / hackney 4.x. 2.3.0 depended on hackney 1.x (~> 1.17 through httpoison 2.2), so these applied to it; all are fixed in the hackney versions 2.4.0 accepts:
    • hackney < 4.0.1 (including 1.x): GHSA-gp9c-pm5m-5cxr (high), GHSA-j9wq-vxxc-94wf (medium), GHSA-pj7v-xfvx-wmjq (medium), GHSA-mp55-p8c9-rfw2 (low)
    • hackney 1.x: GHSA-vq52-99r9-h5pw (low, fixed in 1.21.0) and GHSA-9fm9-hp7p-53mf (low, fixed in 1.24.0)
  • 🔒 Require {:hackney, "~> 4.1"} (now a direct dependency) so that applications cannot resolve a hackney 4.x release, or a quic release, with known advisories. These did not affect 2.3.0, which could not resolve hackney 2.x–4.x or quic; the lower bound only avoids them after the move to hackney 4:
    • hackney >= 2.0.0, < 4.0.1 (hackney 4.0.0 is the 4.x release in this range): GHSA-76v6-f83q-pxvh (high), GHSA-9653-rcfr-5c62 (high), GHSA-q8jg-fgj4-fphf (high), GHSA-jq4m-q6p2-8gwc (high), GHSA-6cp8-v795-jr2j (high), GHSA-f9vr-g2g2-x9fg (medium); and hackney >= 3.1.1, < 4.0.1: GHSA-h73q-4w9q-82h4 (medium)
    • quic <= 1.4.3: GHSA-2r8v-p65x-3663 (critical, broken TLS verification). hackney 4.0.0 requires quic 1.0.0 and hackney 4.0.1 / 4.0.2 require quic 1.4.3, which is why the lower bound is hackney 4.1 (quic 1.4.5) rather than 4.0.1.
  • 🔒 Verified that TLS server certificate verification is enabled by default with hackney 4.x (both 4.1.0 and 4.7.4): verify_peer with the certifi CA bundle, expiry check and hostname check. The library does not pass any ssl / insecure options. (As before, certificate revocation (CRL / OCSP) is not checked.)
  • 🔒 Redirects are not followed, so a 302 from Auth0 is returned as before and credentials (the bearer token, or the client secret sent to /oauth/token) are not re-sent to another host.

Breaking changes

  • 💥 Dependencies move to new major versions: {:httpoison, "~> 3.0"} (was ~> 2.2) and {:hackney, "~> 4.1"} (new direct dependency; was 1.x through httpoison). If your application depends on httpoison 2.x or hackney 1.x directly, upgrade them as well, or dependency resolution will fail.
  • 💥 Elixir 1.17+ and Erlang/OTP 27+ are required (was Elixir 1.12+). mix.exs declares elixir: "~> 1.17"; OTP 27+ is required by hackney 4 and is not enforced by Mix.
  • 💥 HTTPS requests use HTTP/2 by default (negotiated with ALPN; the hackney 4 default). HTTP/3 is not enabled.
  • 💥 When a domain cannot be resolved (DNS failure), the error is {:error, :checkout_timeout} instead of {:error, :nxdomain}, returned after :connect_timeout (8 seconds by default). If you match on :nxdomain, update that code.
  • 💥 An invalid http_protocol (anything other than "https", "http" or nil, including "HTTPS") raises ArgumentError instead of being used as the URL scheme.
  • 💥 http_protocol now also applies to Authentication API requests (/oauth/token, including the token requests made by the token cache). Before, they always used https. With "http", the client secret is sent in plain text.
  • 💥 Invalid recv_timeout / connect_timeout values (anything other than nil or a positive integer, including :infinity) raise ArgumentError.
  • 💥 The library now has an application callback module, Auth0.Application, which starts Auth0.Supervisor (it supervises the token cache) when :auth0_api starts. This is automatic for normal dependencies. If :auth0_api is not started (for example with runtime: false), requests still work, but without the token cache.

Added

  • ✨ Auth0.Config options :recv_timeout (default 5000 ms) and :connect_timeout (default 8000 ms). They apply to all Management API and Authentication API requests, including the token requests made by the token cache. The defaults are the same values that 2.3.0 used (the hackney 1.x defaults); :infinity is not accepted, use a large integer instead.

Changed

  • ⬆️ Upgrade httpoison 2.2.1 → 3.0.0 and hackney 1.20.1 → 4.7.4 (lock file).
  • 🐛 Every request now passes the receive and connect timeouts explicitly. hackney 4 has no receive timeout by default, so without this a request to a server that never responds would never return.
  • 🐛 Requests use a dedicated hackney connection pool per Auth0 domain, named {:auth0_api, domain}, instead of hackney's shared :default pool.
    • hackney 4 opens new connections one at a time inside a pool, so in a shared pool a slow DNS lookup or connect to one host could block requests to other hosts (including your application's own hackney requests) for up to the connect timeout. With a pool per domain, a slow tenant does not affect other tenants or your application.
    • A pool is started by hackney on the first request to a domain and stays until hackney stops, so there is one pool per domain the library has been used with. Use a fixed set of trusted domains (see "Connection pools" in the README).
    • Settings of hackney's :default pool (for example :hackney_pool.set_max_connections(:default, ...)) no longer apply to this library's requests.
  • 📝 Document :http_protocol, :recv_timeout and :connect_timeout in Auth0.Config.

2.3.0

  • ✨ Support Retry-After header for rate limiting
  • ✨ Add Bot Detection Management endpoints (public functions in Auth0.Api.Management added in 2.5.0)
  • ✨ Add Prompts Rendering & Partials endpoints (public rendering functions in Auth0.Api.Management added in 2.5.0)
  • ✨ Add Session Update endpoint (public function in Auth0.Api.Management added in 2.5.0)
  • ✨ Add Client Secret Rotation endpoint
  • ✨ Add Connection Status endpoint
  • ✨ Add Connection Profiles management endpoints
  • ✨ Add Event Streams management endpoints
  • ✨ Add Network ACLs management endpoints
  • ✨ Add User Attribute Profiles management endpoints
  • ✨ Add Token Exchange Profiles management endpoints
  • ✨ Add Verifiable Credentials management endpoints (corrected in 2.5.0: these functions sent requests to a path that does not exist; they now manage verification templates)
  • ✨ Add Risk Assessments management endpoints (corrected in 2.5.0: these endpoints do not exist in the Management API, so the functions are deprecated; the risk assessment settings endpoints are added in 2.5.0)
  • ✨ Add Supplemental Signals management endpoints (corrected in 2.5.0: these endpoints do not exist in the Management API, so the functions are deprecated; the supplemental signals configuration endpoints are added in 2.5.0)
  • ⚠️ Deprecate Rules and Hooks APIs

2.2.0

  • ✨ create api for forms
  • ✨ create api for flows
  • ✨ create api for self service profiles
  • ✨ add api for keys
  • ✨ add api for users
  • ✨ add api for sessions
  • 📝 fix doc comment

2.1.0

  • ✨ add api for branding
  • ✨ add api for connection
  • ✨ add api for guardian
  • ✨ add api for prompts
  • ✨ add api for users
  • 🐛 fix spec type
  • ♻️ move guardian module path
  • 🗑️ remove deprecated api
  • 💥 not to use Params struct and move endpoint consistent
  • 📝 mix docs for each module
  • 💡 update api comment
  • ⬆️ upgrade ex_doc