Configuration

Every setting Auth0Client reads, and what it does. For the minimum needed to make a first call, see the README.

Domain

domain is the whole tenant domain Auth0 gives you, including the region — your-tenant.us.auth0.com, not your-tenant. A domain that does not end in auth0.com raises ArgumentError.

config :auth0_client, domain: System.get_env("AUTH0_DOMAIN")

To use a custom domain, set custom_domain: true to skip that check:

config :auth0_client,
  domain: "auth.example.com",
  custom_domain: true

Using only the Authentication API needs nothing but domain.

Management API credentials

The Management API needs a token. There are two ways to supply one.

A non-interactive client (recommended)

Auth0Client fetches tokens itself and renews them as they expire. Create a machine-to-machine application as described in Auth0's docs, then take the client ID and secret from its settings page:

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 obtained this way are cached and renewed automatically. Only one fetch is ever in flight, so a cold cache under load makes one request to Auth0 rather than one per caller.

If Auth0 rejects a cached token with a 401 — a rotated secret, a revoked client — the token is discarded and the request replayed once with a fresh one, so callers do not need their own retry.

A pre-created token

A token you supply is used for every request as-is. It is never refreshed, and a 401 is not retried, because there is nothing to refresh it with:

config :auth0_client,
  domain: System.get_env("AUTH0_DOMAIN"),
  mgmt_token: System.get_env("AUTH0_MGMT_TOKEN")

token_refresh_skew

How many seconds before expiry a cached token is renewed. Defaults to 60.

config :auth0_client, token_refresh_skew: 120

A token that expires while a request is in flight is rejected, so it is renewed slightly early. Raise this if your requests are long-running or your clock drifts.

http_opts

Passed straight through to Req, which this library uses as its HTTP client. Any Req.request/1 option is valid:

config :auth0_client,
  http_opts: [
    receive_timeout: 30_000,
    connect_options: [timeout: 10_000],
    retry: :safe_transient
  ]

Options are otherwise passed through as written — this library validates exactly one thing.

TLS verification is enforced

Certificate verification is on by default, and connect_options: [transport_opts: [verify: :verify_none]] is refused. Every call this library makes carries your management client secret or a management token, so an unauthenticated connection is not a tradeoff worth offering by accident:

** (ArgumentError) http_opts disables TLS certificate verification ...

If you are reaching for :verify_none because of a private certificate authority — a corporate proxy, a self-signed development host — trust it properly instead:

config :auth0_client,
  http_opts: [connect_options: [transport_opts: [cacertfile: "/path/to/ca.pem"]]]

That is the fix in almost every case. If you genuinely intend to send credentials over an unverified connection, say so explicitly and the library will let you:

config :auth0_client,
  http_opts: [connect_options: [transport_opts: [verify: :verify_none]]],
  dangerously_disable_tls_verification: true

It logs a warning at boot for as long as it is set.

user_agent

The User-Agent sent with every request. Defaults to a string identifying this library. Override it if you want your own application to be identifiable in Auth0's tenant logs:

config :auth0_client, user_agent: "MyApp <https://myapp.example.com>"

Tenant settings

The settings above configure this library. The tenant's own settings — friendly name, default audience and directory, session lifetimes, hosted pages — live in Auth0 and are read and written through the Management API:

Auth0Client.Management.Tenant.settings()
Auth0Client.Management.Tenant.update_settings(%{friendly_name: "Acme"})

Request encoding

You do not configure this, but it is worth knowing that the library does not use one encoding everywhere. Each endpoint follows its own Auth0 documentation: