# Auth0Client

![Build Status](https://github.com/tristanperalta/auth0_client/actions/workflows/main.yml/badge.svg)

> An Elixir client for the Auth0 Management and Authentication APIs, built on Req.

This is a fork of [techgaun/auth0_ex](https://github.com/techgaun/auth0_ex), named `auth0_client`
throughout — the repository, the OTP application, the module namespace and the config key.

It is no longer drop-in compatible with the upstream: the HTTP client is Req rather than HTTPoison, every
failure is a single `Auth0Client.Error` struct, and the deprecated `Login`, `Rule` and `Blacklist` modules
are gone. Migrating from `auth0_ex` means renaming `Auth0Ex` to `Auth0Client`, renaming the `:auth0_ex`
config key to `:auth0_client`, and reading [Error handling](guides/error-handling.md).

## Installation

```elixir
def deps do
  [{:auth0_client, "~> 1.0"}]
end
```

The separate `auth0_ex` package on hex is the upstream this was forked from, and does not contain these
changes.

## Configuration

A `domain`, plus credentials for the Management API if you use it:

```elixir
config :auth0_client,
  domain: System.get_env("AUTH0_DOMAIN"),
  mgmt_client_id: System.get_env("AUTH0_MGMT_CLIENT_ID"),
  mgmt_client_secret: System.get_env("AUTH0_MGMT_CLIENT_SECRET")
```

Tokens are fetched and renewed for you. Using only the Authentication API needs nothing but `domain`.

See [Configuration](guides/configuration.md) for custom domains, pre-created tokens, timeouts and the rest.

## Usage

Each Management resource is a module under `Auth0Client.Management`:

```elixir
Auth0Client.Management.User.all(%{q: "email:*@example.com"})
#=> {:ok, [%{"user_id" => "auth0|abc123", ...}]}
```

Available resources: `Action`, `Client`, `ClientGrant`, `Connection`, `CustomDomain`, `DeviceCredential`,
`EmailProvider`, `Grant`, `Group`, `Guardian`, `Job`, `Key`, `Log`, `Organization`, `RefreshToken`,
`ResourceServer`, `Role`, `Session`, `Tenant`, `Ticket`, `User`, `UserBlock`.

The Authentication API lives under `Auth0Client.Authentication`.

## Guides

| | |
|---|---|
| [Configuration](guides/configuration.md) | Every setting, and what it does |
| [Logging users in](guides/login.md) | Authorization code flow, PKCE, passwordless, signup, logout |
| [Multi-factor authentication](guides/mfa.md) | Configuring factors, enrolling users, completing an MFA login |
| [Managing users](guides/users.md) | User CRUD, search, sessions, bulk import and export |
| [Roles and permissions](guides/rbac.md) | RBAC, and tracing where a user's access came from |
| [Organizations](guides/organizations.md) | B2B — members, org-scoped roles, invitations |
| [Applications and credentials](guides/applications.md) | Clients, Private Key JWT, client grants |
| [Connections and provisioning](guides/connections.md) | Identity providers, SCIM, directory sync |
| [Actions](guides/actions.md) | Extending the login flow |
| [Custom domains and keys](guides/domains-and-keys.md) | Branded login domains, signing-key rotation |
| [Error handling](guides/error-handling.md) | Return shapes, `Auth0Client.Error`, rate limiting |

## API coverage

This library covers a subset of the Auth0 API, and does not wrap endpoints Auth0 has deprecated or
retired. See [CHANGELOG.md](CHANGELOG.md) for what changed in each release, and
[ROADMAP.md](ROADMAP.md) for what is implemented, what is missing, and what is deliberately
excluded.

## Comparison with other Auth0 libraries

Two other hex packages do the same job — calling Auth0's APIs from your server. Compared as of July 2026;
this library moves, so treat its column as a snapshot and check [ROADMAP.md](ROADMAP.md) for current
coverage. `auth0_ex` is the upstream this was forked from.

### Auth0 features

| | **this library** | [auth0_api](https://hex.pm/packages/auth0_api) | [auth0_ex](https://hex.pm/packages/auth0_ex) |
|---|---|---|---|
| **Users** — CRUD, search, blocks | ✅ | ✅ | ✅ |
| **Tickets** — password change, email verification | ✅ | ✅ | ✅ |
| **Roles and permissions** (RBAC) | ✅ | ✅ | — |
| **Organizations** (B2B), groups | ✅ | ✅ | — |
| **Clients and grants** | ✅ | ✅ | ✅ |
| **Connections** | ✅ | ✅ | ✅ |
| **Actions** | ✅ | ✅ | — |
| **MFA** (Guardian) | ✅ | ✅ | — |
| **Custom domains, signing keys** | ✅ | ✅ | — |
| **Jobs** — bulk import/export | ✅ | ✅ | ✅ |
| **Logs, log streams** | ✅ | ✅ | ✅ |
| **Branding, prompts, email templates** | — | ✅ | — |
| **Attack protection, anomaly** | — | ✅ | — |
| **Sessions, refresh tokens** | ✅ | ✅ | — |
| **Login flows** — auth code, PKCE, passwordless | ✅ | — | ✅ |
| **Machine-to-machine tokens** | ✅ | ✅ | ✅ |

### Library qualities

| | **this library** | auth0_api | auth0_ex |
|---|---|---|---|
| Management resource groups | 22 | **~44** | 13 ¹ |
| HTTP client | **Req** | HTTPoison | HTTPoison |
| Single error struct | ✅ | — | — |
| Response headers preserved | ✅ | — | — |
| `Retry-After` on 429 | ✅ | auto-retry ² | — |
| Token cache renews before expiry | ✅ | — ³ | — |
| Single-flight token fetch | ✅ | — | — |
| Cached token redacted from `inspect` | ✅ | — | — |
| Last release | **2026-07** | 2025-12 | 2024-03 |

¹ Includes `rule` and `blacklist`, which Auth0 has deprecated in favour of Actions.
² Retries internally and sleeps the calling process, rather than handing the delay back to you.
³ Treats a token as valid until five seconds *past* its stated expiry.

### Also on hex, for different jobs

None of these call the Management API, so they complement this library rather than replace it:

- **Verifying tokens that arrive on a request** — [auth0_jwks](https://hex.pm/packages/auth0_jwks),
  [prima_auth0_ex](https://hex.pm/packages/prima_auth0_ex),
  [auth0_plug](https://hex.pm/packages/auth0_plug)
- **Browser login as an Ueberauth strategy** — [ueberauth_auth0](https://hex.pm/packages/ueberauth_auth0)

### Which to use

**This library does not verify incoming tokens.** `Auth0Client.Authentication.jwks/0` fetches your tenant's key set, but performs no signature verification and pulls in no crypto library. Pair it with one of the packages above if you need to authenticate requests. That separation is deliberate — verifying a token on the request path is cryptographic work that belongs in a library built for it, and neither Management API package attempts it.

**If you need Management API breadth, use `auth0_api`.** It covers roughly twice the surface, including branding, attack protection, email templates and several 2025-era additions. This library covers the resources most applications actually reach for, and spends its effort on the transport instead: one error struct that carries the response headers, and a management token cache designed for concurrent callers.

## Authors

- [Tristan Peralta](https://github.com/tristanperalta) — maintainer of this fork
- [techgaun](https://github.com/techgaun) — original author of [auth0_ex](https://github.com/techgaun/auth0_ex)