Skip to content

resource-specific-documentation.md

Latest commit

 

History

History
2396 lines (1942 loc) · 72.5 KB

resource-specific-documentation.md

File metadata and controls

2396 lines (1942 loc) · 72.5 KB
Raw

Resource-specific Documentation

In general, the Deploy CLI resource configuration files closely match the payload schemas of the Management API.

However, there are some notable nuances to be aware of:

Client Grants

The Deploy CLI's own client grant is intentionally not exported nor configurable by itself. This is done to prevent breaking changes, otherwise the tool could potentially revoke access or otherwise crash in the midst of an import. In a multi-tenant, multi-environment context, it is expect that new tenants will have a designated client already established for the Deploy CLI, as mentioned in the getting started instructions.

Anonymous Sessions subject type

Client grants support a subject_type field, which is one of client, user, or anonymous_user. Setting subject_type: anonymous_user authorizes a client to obtain anonymous-session access tokens for the given audience. This is the grant that a resource server's require_client_grant anonymous policy checks for (see the Resource Servers section below).

subject_type is immutable. If the subject_type of an existing grant changes, the Deploy CLI deletes the old grant and creates a new one rather than updating it in place.

  • subject_type (string): One of client, user, anonymous_user.
clientGrants:
  - client_id: My Application
    audience: https://api.example.com/
    subject_type: anonymous_user
    scope:
      - read:widgets

Prompts

The prompts resource allows you to configure Universal Login pages, including custom text, custom HTML partials, and screen renderers.

Custom Text: Multilingual text translations follow a hierarchy - language code → prompt ID → screen ID → text ID.

Partials: Custom HTML that can be injected at specific insertion points in prompts.

Screen Renderers: Configure rendering settings for specific prompt-screen combinations. Refer to the Advanced Customizations documentation for more details.

YAML Example

Folder structure when in YAML mode.

./prompts/
    /screenRenderSettings
        /signup-id_signup-id.json
        /login-id_login-id.json
        /login-passwordless_login-passwordless-email-code.json
        /login-passwordless_login-passwordless-sms-otp.json
./tenant.yaml

# Contents of ./tenant.yaml
prompts:
  identifier_first: false
  universal_login_experience: new
  webauthn_platform_first_factor: false
  customText:
    en:
      login:
        login:
          description: Login description in english
          buttonText: Button text
      passkeys:
        passkey-enrollment:
          title: Create a passkey for ${clientName}
          createButtonText: Create a passkey
  partials:
    login:
      login:
        form-content-start: |
          <div class="custom-login-banner">
            <p>Welcome! Please log in to continue.</p>
          </div>
    passkeys:
      passkeys-enrollment:
        form-content-start: |
          <div class="passkey-enrollment-header">
            <p>Enhance your account security by creating a passkey.</p>
          </div>
      passkeys-enrollment-local:
        form-footer-end: |
          <div class="passkey-local-enrollment-info">
            <p>This passkey will be saved to this device only.</p>
          </div>
  screenRenderers:
    - signup-id:
        signup-id: ./prompts/screenRenderSettings/signup-id_signup-id.json
    - login-passwordless:
        login-passwordless-email-code: ./prompts/screenRenderSettings/login-passwordless_login-passwordless-email-code.json
        login-passwordless-sms-otp: ./prompts/screenRenderSettings/login-passwordless_login-passwordless-sms-otp.json

Directory example:

Folder structure when in directory mode.

./prompts/
  ./partials/
    ./login/
      ./login/
        ./form-content-start.liquid
    ./passkeys/
      ./passkeys-enrollment/
        ./form-content-start.liquid
      ./passkeys-enrollment-local/
        ./form-footer-end.liquid
  ./screenRenderSettings/
    ./signup-id_signup-id.json
    ./login-id_login-id.json
    ./login-passwordless_login-passwordless-email-code.json
    ./login-passwordless_login-passwordless-sms-otp.json
    ./login-password_login-password.json
    ./signup-password_signup-password.json
  ./custom-text.json
  ./partials.json
  ./prompts.json

In directory mode, partials.json is a manifest that maps each insertion point to its .liquid file (paths are relative to the prompts/ directory):

Contents of custom-text.json:

{
  "en": {
    "login": {
      "login": {
        "description": "Login description in english",
        "buttonText": "Button text"
      }
    },
    "passkeys": {
      "passkey-enrollment": {
        "title": "Create a passkey for ${clientName}",
        "createButtonText": "Create a passkey"
      }
    }
  }
}

Contents of partials.json:

{
  "login": [
    {
      "login": [
        {
          "name": "form-content-start",
          "template": "partials/login/login/form-content-start.liquid"
        }
      ]
    }
  ],
  "passkeys": [
    {
      "passkeys-enrollment": [
        {
          "name": "form-content-start",
          "template": "partials/passkeys/passkeys-enrollment/form-content-start.liquid"
        }
      ],
      "passkeys-enrollment-local": [
        {
          "name": "form-footer-end",
          "template": "partials/passkeys/passkeys-enrollment-local/form-footer-end.liquid"
        }
      ]
    }
  ]
}

Contents of partials/login/login/form-content-start.liquid:

<div class="login-notice">
  Welcome back! Please log in to continue.
</div>

Contents of partials/passkeys/passkeys-enrollment/form-content-start.liquid:

<div class="passkey-enrollment-header">
  <p>Enhance your account security by creating a passkey.</p>
  <p>Passkeys provide a faster and more secure way to sign in.</p>
</div>

Contents of screenRenderSettings/signup-id_signup-id.json:

{
  "prompt": "signup-id",
  "screen": "signup-id",
  "rendering_mode": "advanced",
  "context_configuration": ["branding.settings", "branding.themes.default"],
  "default_head_tags_disabled": false,
  "head_tags": [
    {
      "tag": "script",
      "attributes": {
        "src": "URL_TO_YOUR_ASSET",
        "async": true,
        "defer": true,
        "integrity": ["ASSET_SHA"]
      }
    }
  ],
  "filters": {
    "match_type": "includes_any",
    "clients": [
      {
        "id": "SeunfRe6p8EXxV6I0g9kMYdT1DxpfC38",
        "metadata": { "key1": "value1" }
      }
    ]
  },
  "use_page_template": false
}

Connections (Google Workspace directory provisioning)

The Deploy CLI supports managing the directory_provisioning_configuration for Google Workspace (google-apps) connections. Only google-apps connections are processed for directory provisioning; other strategies will ignore this block. Deleting directory provisioning requires AUTH0_ALLOW_DELETE=true.

The mapping array pairs Auth0 user fields with IdP fields, and synchronize_automatically controls whether Auth0 runs scheduled sync jobs for the connection.

The synchronize_groups field controls group provisioning. Accepted values are off, all, and selected. When set to selected, the synchronized_groups array specifies which Google Workspace groups to sync. Each group object contains id (required) and optional metadata fields name, email, and direct_members_count populated by the API.

YAML Example

connections:
  - name: google-workspace
    strategy: google-apps
    options:
      domain: example.com
      tenant_domain: example.com
      client_id: 'some_client_id'
      client_secret: 'some_client_secret'
      api_enable_groups: true
      api_enable_users: true
    directory_provisioning_configuration:
      mapping:
        - auth0: email
          idp: mail
        - auth0: name
          idp: displayName
      synchronize_automatically: false
      synchronize_groups: selected
      synchronized_groups:
        - id: 'group-id-1'
          name: 'Engineering'
          email: 'engineering@example.com'
          direct_members_count: 42
        - id: 'group-id-2'
          name: 'Design'
          email: 'design@example.com'
          direct_members_count: 10

Directory Example

./connections/google-apps-directory-provisioning.json

{
  "name": "google-apps-directory-provisioning",
  "strategy": "google-apps",
  "enabled_clients": ["My SPA"],
  "options": {
    "domain": "example.com",
    "tenant_domain": "example.com",
    "client_id": "some_client_id",
    "client_secret": "some_client_secret",
    "api_enable_groups": true,
    "api_enable_users": true
  },
  "directory_provisioning_configuration": {
    "mapping": [
      { "auth0": "email", "idp": "mail" },
      { "auth0": "name", "idp": "displayName" }
    ],
    "synchronize_automatically": false,
    "synchronize_groups": "selected",
    "synchronized_groups": [
      {
        "id": "group-id-1",
        "name": "Engineering",
        "email": "engineering@example.com",
        "direct_members_count": 42
      },
      {
        "id": "group-id-2",
        "name": "Design",
        "email": "design@example.com",
        "direct_members_count": 10
      }
    ]
  }
}

Connections (OIDC and Okta token endpoint authentication options)

For enterprise connections with strategy oidc or okta, the Deploy CLI supports these optional fields under connections[].options:

  • token_endpoint_auth_signing_alg (string): Allowed values are RS256, RS384, RS512, PS256, PS384, ES256, ES384.
  • id_token_signed_response_algs (string[]): Allow-list for incoming ID token signing algorithms. Allowed values are RS256, RS384, RS512, PS256, PS384, ES256, ES384.
  • token_endpoint_jwtca_aud_format (string): Allowed values are issuer or token_endpoint.

YAML Example

connections:
  - name: enterprise-oidc
    strategy: oidc
    enabled_clients:
      - My SPA
    options:
      type: back_channel
      issuer: https://example-idp.com
      jwks_uri: https://example-idp.com/.well-known/jwks.json
      token_endpoint_auth_signing_alg: RS384
      id_token_signed_response_algs:
        - RS256
        - RS384
      token_endpoint_jwtca_aud_format: token_endpoint

Directory Example

./connections/enterprise-oidc.json

{
  "name": "enterprise-oidc",
  "strategy": "oidc",
  "enabled_clients": ["My SPA"],
  "options": {
    "type": "back_channel",
    "issuer": "https://example-idp.com",
    "jwks_uri": "https://example-idp.com/.well-known/jwks.json",
    "token_endpoint_auth_signing_alg": "RS384",
    "id_token_signed_response_algs": ["RS256", "RS384"],
    "token_endpoint_jwtca_aud_format": "token_endpoint"
  }
}

Connections (Cross App Access — Requesting Application)

Early Access: Requires the token_vault_xaa feature flag to be enabled on the tenant.

For enterprise connections with strategy oidc or okta, the Deploy CLI supports configuring the connection as a Requesting Application for Cross App Access via the top-level cross_app_access_requesting_app field:

  • cross_app_access_requesting_app.active (boolean): Set to true to enable the connection as a Requesting Application for Cross App Access. Defaults to true.

YAML Example

connections:
  - name: enterprise-oidc
    strategy: oidc
    cross_app_access_requesting_app:
      active: true
    options:
      type: back_channel
      issuer: https://example-idp.com
      jwks_uri: https://example-idp.com/.well-known/jwks.json

Directory Example

./connections/enterprise-oidc.json

{
  "name": "enterprise-oidc",
  "strategy": "oidc",
  "cross_app_access_requesting_app": {
    "active": true
  },
  "options": {
    "type": "back_channel",
    "issuer": "https://example-idp.com",
    "jwks_uri": "https://example-idp.com/.well-known/jwks.json"
  }
}

Connections (Cross App Access — Resource Application)

Early Access: Part of the XAA (Cross App Access) — Auth0 as Resource Application Authorization Server feature.

The Deploy CLI supports configuring a connection as a Resource Application for Cross App Access via the top-level cross_app_access_resource_app field. This is supported for enterprise connections including SAML (strategy: samlp) and OIDC (strategy: oidc).

  • cross_app_access_resource_app.status ("enabled" | "disabled"): Enables or disables the connection as a Resource Application for Cross App Access.

For SAML connections, the discovery_url and oidc_metadata connection options — previously only supported for OIDC connections — are now also accepted under options.

YAML Example

connections:
  - name: enterprise-saml
    strategy: samlp
    cross_app_access_resource_app:
      status: enabled
    options:
      discovery_url: https://example-idp.com/.well-known/openid-configuration
      oidc_metadata:
        issuer: https://example-idp.com

Directory Example

./connections/enterprise-saml.json

{
  "name": "enterprise-saml",
  "strategy": "samlp",
  "cross_app_access_resource_app": {
    "status": "enabled"
  },
  "options": {
    "discovery_url": "https://example-idp.com/.well-known/openid-configuration",
    "oidc_metadata": {
      "issuer": "https://example-idp.com"
    }
  }
}

Clients (Cross App Access — Identity Assertion Authorization Grant)

Early Access: Part of the XAA (Cross App Access) — Auth0 as Resource Application Authorization Server feature.

The Deploy CLI supports the identity_assertion_authorization_grant property on clients, which enables the client to participate in Cross App Access (ID-JAG) token exchange.

  • identity_assertion_authorization_grant.active (boolean): Set to true to enable ID-JAG exchange for the client.
clients:
  - name: My XAA Client
    identity_assertion_authorization_grant:
      active: true

Clients (Anonymous Sessions)

The Deploy CLI supports the anonymous_sessions property on clients, which controls whether the client can start anonymous sessions.

  • anonymous_sessions.active (boolean): Set to true to enable anonymous sessions for the client.

YAML Example

clients:
  - name: My Application
    anonymous_sessions:
      active: true

Directory Example

{
  "name": "My Application",
  "anonymous_sessions": {
    "active": true
  }
}

Databases

When managing database connections, the values of options.customScripts point to specific javascript files relative to the path of the output folder. Otherwise, the payload closely matches that of the Management API.

YAML Example

Folder structure when in YAML mode.

./databases/
    /Username-Password-Authentication
        /change_password.js
        /create.js
        /delete.js
        /get_user.js
        /login.js
        /verify.js
./tenant.yaml

# Contents of ./tenant.yaml
databases:
  - name: Username-Password-Authentication
    # ...
    options:
      # ...
      customScripts:
        change_password: ./databases/Username-Password-Authentication/change_password.js
        create: ./databases/Username-Password-Authentication/create.js
        delete: ./databases/Username-Password-Authentication/delete.js
        get_user: ./databases/Username-Password-Authentication/get_user.js
        login: ./databases/Username-Password-Authentication/login.js
        verify: ./databases/Username-Password-Authentication/verify.js

Directory Example

Folder structure when in directory mode.

./database-connections/
    ./Username-Password-Authentication/
        ./change_password.js
        ./create.js
        ./database.json
        ./delete.js
        ./get_user.js
        ./login.js
        ./verify.js

Contents of database.json

{
  "options": {
    "customScripts": {
      "change_password": "./change_password.js",
      "create": "./create.js",
      "delete": "./delete.js",
      "get_user": "./get_user.js",
      "login": "./login.js",
      "verify": "./verify.js"
    }
  }
}

Resource Servers

Resource servers (APIs) configuration supports the Management API payload schema. The following fields are supported:

YAML Example

resourceServers:
  - name: My API
    identifier: https://api.example.com
    proof_of_possession:
      mechanism: dpop
      required: true
      required_for: public_clients

Directory Example

{
  "name": "My API",
  "identifier": "https://api.example.com",
  "proof_of_possession": {
    "mechanism": "mtls",
    "required": true,
    "required_for": "all_clients"
  }
}

Auth0 My Account API — authorization_policy

The authorization_policy field can be set on the Auth0 My Account API resource server (the system resource server with identifier https://<tenant-domain>/me/) when the acr feature flag is enabled on the tenant. It specifies an Authentication Context Class Reference (ACR) policy that controls the authentication assurance requirements for access tokens issued to that API.

YAML Example

resourceServers:
  - name: Auth0 My Account API
    identifier: https://your-tenant.auth0.com/me/
    authorization_policy:
      policy_id: '019b76da-a800-73c9-b656-b349ae415c17'

To clear the policy, set it to null:

resourceServers:
  - name: Auth0 My Account API
    identifier: https://your-tenant.auth0.com/me/
    authorization_policy: null

Directory Example

{
  "name": "Auth0 My Account API",
  "identifier": "https://your-tenant.auth0.com/me/",
  "authorization_policy": {
    "policy_id": "019b76da-a800-73c9-b656-b349ae415c17"
  }
}

Note: authorization_policy is only accepted by the Auth0 API for the My Account resource server and only when the acr feature flag is enabled on the tenant.

Online Refresh Tokens — allow_online_access and allow_online_access_with_ephemeral_sessions

The allow_online_access field enables issuance of Online Refresh Tokens (ORTs) for a resource server. ORTs are stateless, non-rotating tokens bound to the Auth0 session lifetime — when the session expires or is revoked, the ORT becomes invalid.

allow_online_access_with_ephemeral_sessions permits ORT issuance even when the session uses a non-persistent (ephemeral) cookie. This field can only be set to true if allow_online_access is also true.

Both fields default to false and require the online_refresh_tokens feature flag to be enabled on the tenant.

YAML Example

resourceServers:
  - name: My API
    identifier: https://api.example.com
    allow_online_access: true
    allow_online_access_with_ephemeral_sessions: false

Directory Example

{
  "name": "My API",
  "identifier": "https://api.example.com",
  "allow_online_access": true,
  "allow_online_access_with_ephemeral_sessions": false
}

Anonymous Sessions: subject_type_authorization.anonymous_user, token_lifetime_for_anonymous_access_tokens, and access_token.claims_mapping

The Deploy CLI supports the resource server fields that configure anonymous-session access tokens:

  • subject_type_authorization.anonymous_user.policy (string): The access policy for anonymous user flows. One of deny_all or require_client_grant. This sits alongside the existing user and client policies. Note that subject_type_authorization does not allow unknown properties, so anonymous_user must be spelled exactly as shown.
  • token_lifetime_for_anonymous_access_tokens (number): Expiration value, in seconds, for anonymous-session access tokens issued for this API.
  • access_token.claims_mapping.custom_claims (array): Custom claims to emit in anonymous-session access tokens. Each rule maps a value read from the anonymous-session context onto a named access-token claim, and has two fields:
    • name (string): The access-token claim name to emit.
    • expression (string): A restricted dot-path expression read from the anonymous-session context (for example anonymous_session.metadata.country).

When the anonymous policy is require_client_grant, a client must hold a client grant with subject_type: anonymous_user for this audience (see the Client Grants section above).

YAML Example

resourceServers:
  - name: My API
    identifier: https://api.example.com
    subject_type_authorization:
      user:
        policy: allow_all
      client:
        policy: require_client_grant
      anonymous_user:
        policy: require_client_grant
    token_lifetime_for_anonymous_access_tokens: 3600
    access_token:
      claims_mapping:
        custom_claims:
          - name: country
            expression: anonymous_session.metadata.country

Directory Example

{
  "name": "My API",
  "identifier": "https://api.example.com",
  "subject_type_authorization": {
    "user": { "policy": "allow_all" },
    "client": { "policy": "require_client_grant" },
    "anonymous_user": { "policy": "require_client_grant" }
  },
  "token_lifetime_for_anonymous_access_tokens": 3600,
  "access_token": {
    "claims_mapping": {
      "custom_claims": [{ "name": "country", "expression": "anonymous_session.metadata.country" }]
    }
  }
}

Universal Login

Pages

When overriding the Universal Login with custom HTML, the error, login, multi-factor authentication and password reset contents are organized in specific HTML pages.

YAML Example

Folder structure when in YAML mode.

./pages/
    /error_page.html
    /guardian_multifactor.html
    /login.html
    /password_reset.html
./tenant.yaml

# Contents of ./tenant.yaml
pages:
  - name: error_page
    html: ./pages/error_page.html
    show_log_link: false
    url: https://mycompany.org/error
  - name: guardian_multifactor
    enabled: true
    html: ./pages/guardian_multifactor.html
  - name: login
    enabled: false
    html: ./pages/login.html
  - name: password_reset
    enabled: true
    html: ./pages/password_reset.html

Directory Example

Folder structure when in directory mode.

./pages/
    ./error_page.html
    ./error_page.json
    ./guardian_multifactor.html
    ./guardian_multifactor.json
    ./login.html
    ./login.json
    ./password_reset.html
    ./password_reset.json

Contents of login.json

{
  "name": "login",
  "enabled": false,
  "html": "./login.html"
}

Contents of error_page.json

{
  "html": "./error_page.html",
  "show_log_link": false,
  "url": "https://mycompany.org/error",
  "name": "error_page"
}

Contents of guardian_multifactor.json

{
  "enabled": true,
  "html": "./guardian_multifactor.html",
  "name": "guardian_multifactor"
}

Contents of password_reset.json

{
  "enabled": true,
  "html": "./password_reset.html",
  "name": "password_reset"
}

emailTemplates

When managing email templates, the values of options.body and options.body point to specific HTML files relative to the path of the output folder. Otherwise, the payload closely matches that of the Management API.

YAML Example

Folder structure when in YAML mode.

./emailTemplates/
    ./verify_email.html
    ./welcome_email.html
    ./password_reset.html
    ./reset_email.html
    ./reset_email_by_code.html
./tenant.yaml

# Contents of ./tenant.yaml
emailTemplates:
  - template: 'verify_email'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

  - template: 'welcome_email'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

  - template: 'password_reset'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

  - template: 'reset_email_by_code'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

Directory Example

Folder structure when in directory mode.
./emailTemplates/
    ./welcome_email.html
    ./welcome_email.json
    ./reset_email.html
    ./reset_email.json
    ./reset_email_by_code.html
    ./reset_email_by_code.json

Contents of welcome_email.json

{
  "name": "welcome_email",
  "enabled": true,
  "html": "./welcome_email.html"
}

Contents of reset_email.json

{
  "name": "reset_email",
  "enabled": true,
  "html": "./reset_email.html"
}

Contents of reset_email_by_code.json

{
  "name": "reset_email_by_code",
  "enabled": true,
  "html": "./reset_email_by_code.html"
}

Branding

This resource allows to manage branding within your Auth0 tenant. Auth0 can be customized with a look and feel that aligns with your organization's brand requirements and user expectations. universal_login template can be customized (make sure to add read:custom_domains scope to export templates).

YAML Example

Folder structure when in YAML mode.

branding:
  colors:
    page_background: '#FF4F40'
    primary: '#2A2E35'
  favicon_url: https://example.com/favicon.png
  font:
    url: https://example.com/font.woff
  logo_url: https://example.com/logo.png
  templates:
    - template: universal_login
      body: ./branding_templates/universal_login.html

Directory Example

Folder structure when in directory mode.

{
  "colors": {
    "page_background": "#FF4F40",
    "primary": "#2A2E35"
  },
  "favicon_url": "https://example.com/favicon.png",
  "font": {
    "url": "https://example.com/font.woff"
  },
  "logo_url": "https://example.com/logo.png"
}

For universal_login template templates/ will be created.

  • templates/universal_login.html
<!DOCTYPE html>
<html>
  <head>
    {%- auth0:head -%}
  </head>
  <body>
    {%- auth0:widget -%}
    <div>page teamplate</div>
  </body>
</html>
  • templates/universal_login.json
{
  "template": "universal_login",
  "body": "./universal_login.html"
}

Themes (Identifier display settings)

Early Access: Requires the universal_login_theme_identifiers feature flag to be enabled on the tenant. When the flag is off, the Auth0 API rejects a theme write that includes identifiers and strips the field from responses.

The Deploy CLI supports configuring identifier display settings on the branding theme via the top-level identifiers object. All three members are required when identifiers is supplied:

  • identifiers.login_display (string): Login display mode. One of separate, unified.
  • identifiers.otp_autocomplete (boolean): Whether OTP autocomplete is enabled.
  • identifiers.phone_display (object): Phone number display settings.
    • identifiers.phone_display.formatting (string): One of international, regional.
    • identifiers.phone_display.masking (string): One of hide_country_code, mask_digits, show_all.

YAML Example

themes:
  - displayName: Default theme
    borders: { ... }
    colors: { ... }
    fonts: { ... }
    page_background: { ... }
    widget: { ... }
    identifiers:
      login_display: unified
      otp_autocomplete: true
      phone_display:
        masking: mask_digits
        formatting: international

Directory Example

./themes/Default theme.json

{
  "displayName": "Default theme",
  "borders": { "...": "..." },
  "colors": { "...": "..." },
  "fonts": { "...": "..." },
  "page_background": { "...": "..." },
  "widget": { "...": "..." },
  "identifiers": {
    "login_display": "unified",
    "otp_autocomplete": true,
    "phone_display": {
      "masking": "mask_digits",
      "formatting": "international"
    }
  }
}

Tenant Settings (Country codes)

Early Access: Requires the tenant_country_codes_filtering feature flag to be enabled on the tenant. When the flag is off, the Auth0 API rejects a tenant settings write that includes country_codes.

The Deploy CLI supports configuring phone country code filtering for identifier input via the top-level country_codes object in tenant settings:

  • country_codes.list (array of string): ISO 3166-1 alpha-2 codes (e.g. US, GB). Must be non-empty and unique.
  • country_codes.mode (string): Whether the list is an allowlist or denylist. One of allow, deny.

Set country_codes: null to remove filtering (allow all countries).

YAML Example

tenant:
  country_codes:
    list:
      - US
      - GB
      - CA
    mode: allow

Directory Example

./tenant.json

{
  "country_codes": {
    "list": ["US", "GB", "CA"],
    "mode": "allow"
  }
}

Tenant Settings (Anonymous Sessions)

The Deploy CLI supports configuring anonymous session behavior via the top-level sessions.anonymous object in tenant settings:

  • sessions.anonymous.lifetime_in_minutes (integer): The lifetime of an anonymous session, in minutes.
  • sessions.anonymous.activate_cookie (boolean): Whether to activate the anonymous session cookie.

Other keys under sessions are passed through untouched, so unmanaged session settings are preserved.

YAML Example

tenant:
  sessions:
    anonymous:
      lifetime_in_minutes: 120
      activate_cookie: true

Directory Example

./tenant.json

{
  "sessions": {
    "anonymous": {
      "lifetime_in_minutes": 120,
      "activate_cookie": true
    }
  }
}

Custom Domains

Custom domains allow you to use your own domain for authentication instead of the default Auth0 domain. The Deploy CLI supports managing custom domains in both directory and YAML modes.

Custom domains have the following key properties:

  • domain: The custom domain name (required)
  • type: Certificate management type - either auth0_managed_certs or self_managed_certs (required)
  • custom_client_ip_header: Header to use for client IP detection (optional, one of: true-client-ip, cf-connecting-ip, x-forwarded-for, or null)
  • tls_policy: TLS policy to use (defaults to recommended)
  • verification_method: Domain verification method (defaults to txt)
  • domain_metadata: Metadata associated with the custom domain (optional, max 10 properties)
  • relying_party_identifier: Relying Party ID (rpId) to be used for Passkeys on this custom domain. If not provided or set to null, the full domain will be used. (optional)

Note: The relying_party_identifier should be a suffix of the domain name. For example, if your domain is auth.example.com, the relying_party_identifier could be example.com.

YAML Example

# Contents of ./tenant.yaml
customDomains:
  - domain: 'auth.example.com'
    type: 'auth0_managed_certs'
    tls_policy: 'recommended'
    custom_client_ip_header: 'cf-connecting-ip'
    domain_metadata:
      environment: 'production'
      team: 'platform'
    relying_party_identifier: 'example.com'
  - domain: 'login.myapp.com'
    type: 'self_managed_certs'
    verification_method: 'txt'

Directory Example

Folder structure when in directory mode.

./customDomains/
    ./auth.example.com.json
    ./login.myapp.com.json

Contents of auth.example.com.json:

{
  "domain": "auth.example.com",
  "type": "auth0_managed_certs",
  "tls_policy": "recommended",
  "custom_client_ip_header": "cf-connecting-ip",
  "domain_metadata": {
    "environment": "production",
    "team": "platform"
  },
  "relying_party_identifier": "example.com"
}

Contents of login.myapp.com.json:

{
  "domain": "login.myapp.com",
  "type": "self_managed_certs",
  "verification_method": "txt"
}

For more details, see the Management API documentation.

NetworkACL

Tenant Network Access Control Lists (NetworkACLs) allow you to configure rules that control access to your Auth0 tenant based on IP addresses, geographical locations, and other network criteria. The Deploy CLI supports managing NetworkACLs in both directory and YAML modes.Refer more on this.

NetworkACLs have the following key properties:

  • description: A descriptive name for the rule
  • active: Boolean indicating if the rule is active
  • priority: Number (minimum 1) determining the order of rule evaluation (lower numbers have higher priority)
  • rule: The rule configuration containing:
    • action: The action to take (block, allow, log, or redirect)
    • scope: The scope of the rule ('management', 'authentication', or 'tenant')
    • match, not_match, or match_all: Criteria for matching requests

The match and not_match criteria also support an auth0_managed array for matching Auth0-managed IP ranges (e.g. auth0.icloud_relay_proxy, auth0.low_reputation). Each value must follow the pattern ^auth0\.[^.\s]+$. This is an Early Access feature gated behind the tenant_acl_curated_blocklists feature flag and requires the advanced-breached-password-detection entitlement; the API rejects rules using auth0_managed with an HTTP 403 if the tenant is not entitled.

Set match_all: true for a rule that unconditionally matches all traffic (e.g. block or allow everything within a scope), with no other signal required. match_all is mutually exclusive with match and not_match — a rule may use only one of the three, and combining them is rejected. Only true is valid; omit the property rather than setting it to false. match_all is gated behind the tenant_acl_match_all feature flag, and the API rejects rules using it with an HTTP 400 if the tenant does not have the flag enabled.

YAML Example

# Contents of ./tenant.yaml
networkACLs:
  - description: 'Allow Specific Countries'
    active: true
    priority: 2
    rule:
      action:
        allow: true
      scope: 'authentication'
      match:
        geo_country_codes: ['US', 'CA']
  - description: 'Redirect Specific User Agents'
    active: true
    priority: 3
    rule:
      action:
        block: true
      scope: 'management'
      not_match:
        user_agents: ['BadBot/1.0']
  - description: 'Block iCloud Private Relay Exits'
    active: true
    priority: 4
    rule:
      action:
        block: true
      scope: 'tenant'
      match:
        auth0_managed: ['auth0.icloud_relay_proxy']
  - description: 'Block All Tenant Traffic'
    active: true
    priority: 99
    rule:
      action:
        block: true
      scope: 'tenant'
      match_all: true

Directory Example

Folder structure when in directory mode.

./networkACLs/
    ./Allow Specific Countries-p-2.json
    ./Redirect Specific User Agents-p-3.json
    ./Block iCloud Private Relay Exits-p-4.json
    ./Block All Tenant Traffic-p-99.json

Contents of Allow Specific Countries-p-2.json:

{
  "description": "Allow Specific Countries",
  "active": true,
  "priority": 2,
  "rule": {
    "action": {
      "allow": true
    },
    "scope": "authentication",
    "match": {
      "geo_country_codes": ["US", "CA"]
    }
  }
}

Contents of Redirect Specific User Agents-p-3.json:

{
  "description": "Redirect Specific User Agents",
  "active": true,
  "priority": 3,
  "rule": {
    "action": {
      "block": true
    },
    "scope": "management",
    "match": {
      "user_agents": ["BadBot/1.0"]
    }
  }
}

Contents of Block iCloud Private Relay Exits-p-4.json:

{
  "description": "Block iCloud Private Relay Exits",
  "active": true,
  "priority": 4,
  "rule": {
    "action": {
      "block": true
    },
    "scope": "tenant",
    "match": {
      "auth0_managed": ["auth0.icloud_relay_proxy"]
    }
  }
}

Contents of Block All Tenant Traffic-p-99.json:

{
  "description": "Block All Tenant Traffic",
  "active": true,
  "priority": 99,
  "rule": {
    "action": {
      "block": true
    },
    "scope": "tenant",
    "match_all": true
  }
}

NetworkACL Keys

Network ACL Keys are HMAC signing keys used for HTTP message signature verification in Network ACL rules. Each key has a name, an algorithm (hmac-sha256), and a server-computed fingerprint. The Deploy CLI supports creating and deleting NetworkACL keys.

Note: This feature requires the tenant_acl_hmac_signature and tenant_acl_management_api feature flags plus the tenant-access-control entitlement. Contact Auth0 support if the feature is not available on your tenant.

NetworkACL keys have the following properties:

  • name: Unique name for the key (max 255 characters)
  • alg: Signing algorithm — currently only hmac-sha256
  • value: The raw key material (write-only — never returned by the API, not exported). Supply via keyword replacement (e.g. ##HMAC_KEY_VALUE##) mapped from an environment variable or CI secret.
  • fingerprint: SHA-256 fingerprint of the key (read-only, set by the API, exported for reference)

Keys are immutable after creation. To rotate a key, delete the old one and create a new one with a different name.

Warning: Deleting a key that is still referenced by an ACL rule will return HTTP 409. Remove all rule references first.

Supplying the key value

The value field is write-only and is never returned by the API. At deploy time, supply it using keyword replacement:

# config.json (or environment variables)
# HMAC_KEY_VALUE=<your-secret-key-material>

# tenant.yaml
networkACLKeys:
  - name: my-hmac-key-v1
    alg: hmac-sha256
    value: ##HMAC_KEY_VALUE##

If value is omitted from the config, the Deploy CLI will log a warning and skip creating that key. This is useful for tracking existing keys (by name and fingerprint) without re-supplying the secret.

YAML Example

# Contents of ./tenant.yaml
networkACLKeys:
  - name: my-hmac-key-v1
    alg: hmac-sha256
    value: ##HMAC_KEY_VALUE##    # omitted on export; supply at deploy time
    fingerprint: ee66b47a0b3e356a0d7c587bd1e2ed3790b46fdbd657dbeb409f30de76a14cc3

Directory Example

Folder structure when in directory mode.

./network-acl-keys/
    ./my-hmac-key-v1.json

Contents of my-hmac-key-v1.json:

{
  "name": "my-hmac-key-v1",
  "alg": "hmac-sha256",
  "fingerprint": "ee66b47a0b3e356a0d7c587bd1e2ed3790b46fdbd657dbeb409f30de76a14cc3"
}

Using a key in a NetworkACL rule

Once a key is deployed, reference it by id in an ACL rule's http_message_signature signal:

networkACLs:
  - description: 'Require HMAC signature'
    active: true
    priority: 1
    rule:
      action:
        allow: true
      scope: 'authentication'
      match:
        http_message_signature:
          keys:
            - id: <key-id> # the id returned by the API after key creation

Organizations

The deploy CLI supports managing organizations, including their connections, client grants, discovery domains, and org-to-app entitlement settings.

Org-to-App Entitlement (is_app_entitlement_active / clients)

Note: Requires the org_to_app_entitlement_enabled feature flag to be enabled on the tenant.

is_app_entitlement_active controls whether org-to-app entitlement is active for an organization. When active, the clients array specifies which client applications org members are entitled to use for login.

Each entry in clients has:

  • client_id — the name of the client application (resolved to the actual ID at deploy time)
  • use_for_member_access — when true, org members can use this client to log in

YAML Example

organizations:
  - name: my-organization
    display_name: My Organization
    is_app_entitlement_active: true
    clients:
      - client_id: My App
        use_for_member_access: true

Directory Example

./organizations/my-organization.json

{
  "name": "my-organization",
  "display_name": "My Organization",
  "is_app_entitlement_active": true,
  "clients": [
    {
      "client_id": "My App",
      "use_for_member_access": true
    }
  ]
}

Note: When exporting, client_id values are resolved to client names for portability across environments. On deploy, names are resolved back to IDs. The M2M application used by the deploy CLI requires the read:organization_clients, create:organization_clients, update:organization_clients, and delete:organization_clients scopes.

PhoneProviders

When managing phone providers, credentials are never exported.

For the Twilio phoneProvider, we add the placeholder ##TWILIO_AUTH_TOKEN## for the credential's auth_token, which can be used with keyword replacement.

Refer to keyword-replacement.md, multi-environment-workflow.md, and the Management API for more details.

YAML Example

# Contents of ./tenant.yaml
phoneProviders:
  - name: twilio
    configuration:
      sid: 'twilio_sid'
      default_from: '+1234567890'
      delivery_methods:
        - text
        - voice
    disabled: false
    credentials:
      auth_token: '##TWILIO_AUTH_TOKEN##'

Directory Example

[
  {
    "name": "twilio",
    "disabled": true,
    "configuration": {
      "sid": "twilio_sid",
      "default_from": "+1234567890",
      "delivery_methods": ["text", "voice"]
    },
    "credentials": {
      "auth_token": "##TWILIO_AUTH_TOKEN##"
    }
  }
]

PhoneTemplates

Phone templates allow you to customize the SMS and voice messages sent to users for phone-based authentication. Refer to the Management API for more details.

YAML Example

# Contents of ./tenant.yaml
phoneTemplates:
  - type: otp_verify
    disabled: false
    content:
      from: '+12341234567'
      body:
        text: 'Your verification code is {{ code }}'
        voice: 'Your verification code is {{ code }}'
  - type: otp_enroll
    disabled: false
    content:
      from: '+12341234567'
      body:
        text: 'Your enrollment code is {{ code }}'

Directory Example

Create individual JSON files for each template in the phone-templates directory:

phone-templates/
├── otp_verify.json
├── otp_enroll.json
├── change_password.json
└── ...

Example phone-templates/otp_verify.json:

{
  "type": "otp_verify",
  "disabled": false,
  "content": {
    "from": "+12341234567",
    "body": {
      "text": "Your verification code is {{ code }}",
      "voice": "Your verification code is {{ code }}"
    }
  }
}

Connection Profiles

Application specific configuration for use with the OIN Express Configuration feature

The cross_app_access_resource_app field controls whether organization admins may enable Cross App Access (XAA) on their Identity Providers:

  • cross_app_access_resource_app.status.default_value ("enabled" | "disabled"): The default Cross App Access resource app status.
  • cross_app_access_resource_app.status.allowed_values (array of "enabled" | "disabled"): The allowed status values.

YAML Example

# Contents of ./tenant.yaml
connectionProfiles:
  - name: 'Enterprise SSO Profile'
    organization:
      show_as_button: 'required'
      assign_membership_on_login: 'required'
    connection_name_prefix_template: 'org-{organization_name}'
    enabled_features:
      - scim
      - universal_logout
    cross_app_access_resource_app:
      status:
        default_value: 'enabled'
        allowed_values:
          - enabled
          - disabled
    strategy_overrides:
      samlp:
        enabled_features:
          - universal_logout
      oidc:
        enabled_features:
          - scim
          - universal_logout
  - name: 'Basic Connection Profile'
    organization:
      show_as_button: 'optional'
      assign_membership_on_login: 'optional'
    enabled_features:
      - scim

Directory Example

File: ./connection-profiles/Enterprise SSO Profile.json

{
  "name": "Enterprise SSO Profile",
  "organization": {
    "show_as_button": "required",
    "assign_membership_on_login": "required"
  },
  "connection_name_prefix_template": "org-{organization_name}",
  "enabled_features": ["scim", "universal_logout"],
  "cross_app_access_resource_app": {
    "status": {
      "default_value": "enabled",
      "allowed_values": ["enabled", "disabled"]
    }
  },
  "strategy_overrides": {
    "samlp": {
      "enabled_features": ["universal_logout"]
    },
    "oidc": {
      "enabled_features": ["scim", "universal_logout"]
    }
  }
}

B2B Integration Configuration on Clients

Early Access — requires the enterprise_connect_entitled entitlement on your tenant.

The b2b_integration_configuration object enables Enterprise Connect functionality on a client. It can be set at creation time regardless of app_type. Once set, it can be updated via deploy as normal.

Important: b2b_integration_configuration cannot be added to an existing client via PATCH. If you need to add it to a client that was created without it, re-create the client. The deploy-cli will warn and skip the field if this constraint is violated.

The integration_type field accepts one of: custom_auth_server, third_party, application.

clients:
  - name: 'My B2B Integration Client'
    app_type: 'spa'
    b2b_integration_configuration:
      integration_type: 'custom_auth_server'

To clear b2b_integration_configuration, set it to null:

clients:
  - name: 'My B2B Integration Client'
    app_type: 'spa'
    b2b_integration_configuration: null

My Organization Member Management on Clients

Early Access — requires the my_org_member_management_ea feature flag on your tenant.

Two boolean fields control member management behaviour for the My Organization API. Both are nested under my_organization_configuration on the client object.

Field Type Default Description
enforce_permission_ceiling boolean false When true, limits the permissions that organization admins can assign to members to only those held by the admin themselves.
enforce_self_assignment_restriction boolean false When true, prevents organization admins from assigning permissions to themselves.

FF gating behaviour: When the feature flag is off, the API strips both fields from GET responses (export produces no fields) and returns 403 UNSUPPORTED_OPERATION if either field is included in a PATCH/POST payload — even when set to false. The deploy-cli surfaces this error to the user.

Export behaviour for false values: The API omits these fields from GET responses when their value is false. As a result, exported YAML will only contain enforce_permission_ceiling or enforce_self_assignment_restriction when they are true. This is expected — a missing field in the export means the value is false.

Omitting a field resets it to false: If you include my_organization_configuration in your config but omit one of the enforce fields, the API treats the omitted field as false on the next deploy. To preserve an existing true value you must explicitly include the field.

clients:
  - name: 'My Organization App'
    app_type: 'regular_web'
    my_organization_configuration:
      allowed_strategies:
        - oidc
      connection_deletion_behavior: allow
      enforce_permission_ceiling: true
      enforce_self_assignment_restriction: true

To disable the restrictions, either omit the fields or set them explicitly to false:

clients:
  - name: 'My Organization App'
    app_type: 'regular_web'
    my_organization_configuration:
      allowed_strategies:
        - oidc
      connection_deletion_behavior: allow
      enforce_permission_ceiling: false
      enforce_self_assignment_restriction: false

Express Configuration on Clients

Connection profiles are used in conjunction with the express_configuration property on client applications: (In order to use express_configuration app_type should not be 'express_configuration')

clients:
  - name: 'My Enterprise App'
    app_type: 'regular_web'
    express_configuration:
      initiate_login_uri_template: 'https://myapp.com/sso/start?org={organization_name}&conn={connection_name}'
      user_attribute_profile_id: 'My User Attribute Profile'
      connection_profile_id: 'Enterprise SSO Profile' # Reference to connection profile
      enable_client: true
      enable_organization: true
      okta_oin_client_id: 'My Okta OIN Client'
      admin_login_domain: 'login.myapp.com'
      linked_clients:
        - client_id: 'client_id_of_mobile_app'

For more details, see the Management API documentation.

Self-Service Profiles

Self-Service Profiles enable organizations to configure self-service SSO flows for their users. These profiles define the user attributes to collect, branding customization, and which identity provider strategies are allowed during the self-service setup process.

Note: You cannot specify both user_attribute_profile_id and user_attributes in the same profile. Use user_attribute_profile_id to reference an existing User Attribute Profile, or define user_attributes inline.

YAML Example

# Contents of ./tenant.yaml
selfServiceProfiles:
  - name: 'Enterprise SSO Profile'
    description: 'Self-service SSO for enterprise customers'
    allowed_strategies:
      - oidc
      - samlp
      - okta
    user_attributes:
      - name: email
        description: Email of the User
        is_optional: false
      - name: name
        description: Name of the User
        is_optional: true
    branding:
      logo_url: 'https://example.com/logo.png'
      colors:
        primary: '#19aecc'
    customText:
      en:
        get-started:
          introduction: 'Welcome! With <p>only a few steps</p> you will be able to setup your new connection.'

  - name: 'Simple SSO Profile'
    description: 'Basic SSO profile'
    user_attribute_profile_id: 'My User Attribute Profile'
    allowed_strategies:
      - google-apps
      - adfs

Directory Example

Folder structure when in directory mode.

./self-service-profiles/
    ./Enterprise SSO Profile.json
    ./Simple SSO Profile.json

Contents of Enterprise SSO Profile.json:

{
  "name": "Enterprise SSO Profile",
  "description": "Self-service SSO for enterprise customers",
  "allowed_strategies": ["oidc", "samlp", "okta"],
  "user_attributes": [
    {
      "name": "email",
      "description": "Email of the User",
      "is_optional": false
    },
    {
      "name": "name",
      "description": "Name of the User",
      "is_optional": true
    }
  ],
  "branding": {
    "logo_url": "https://example.com/logo.png",
    "colors": {
      "primary": "#19aecc"
    }
  },
  "customText": {
    "en": {
      "get-started": {
        "introduction": "Welcome! With <p>only a few steps</p> you will be able to setup your new connection."
      }
    }
  }
}

Contents of Simple SSO Profile.json:

{
  "name": "Simple SSO Profile",
  "description": "Basic SSO profile",
  "user_attribute_profile_id": "My User Attribute Profile",
  "allowed_strategies": ["google-apps", "adfs"]
}

For more details, see the Management API documentation.

Risk Assessments

Risk assessments configuration allows you to enable or disable risk assessment features for your tenant.

Entitlement required: Risk assessments are part of Adaptive MFA, which requires an Enterprise add-on. On tenants without this entitlement, export and deploy of riskAssessment will be skipped with a warning.

  • settings.enabled: toggles the feature true/flase (required)
  • new_device.remember_for (optional): days to remember devices

YAML Example

# Contents of ./tenant.yaml
riskAssessment:
  settings:
    enabled: true
  new_device:
    remember_for: 30

Directory Example

Folder: ./risk-assessment/

File: ./risk-assessment/settings.json

{
  "settings": {
    "enabled": true
  },
  "new_device": {
    "remember_for": 30
  }
}

For more details, see the Management API documentation.

Action Modules

Action modules are reusable code modules that can be shared across multiple Auth0 actions. They allow you to create common utility functions, helpers, and libraries that can be imported and used by any action in your tenant.

YAML Example

# Contents of ./tenant.yaml
actionModules:
  - name: auth-helper
    code: ./action-modules/auth-helper/code.js
    dependencies:
      - name: axios
        version: 1.6.0
      - name: jsonwebtoken
        version: 9.0.0
    secrets:
      - name: JWT_SECRET
        value: ##JWT_SECRET##

  - name: notification-helper
    code: ./action-modules/notification-helper/code.js
    dependencies:
      - name: uuid
        version: 9.0.0
    secrets: []

Folder structure when in YAML mode:

./action-modules/
    /auth-helper/
        /code.js
    /notification-helper/
        /code.js
./tenant.yaml

Directory Example

Folder structure when in directory mode:

./action-modules/
    ./auth-helper.json
    ./auth-helper/
        ./code.js
    ./notification-helper.json
    ./notification-helper/
        ./code.js

Contents of auth-helper.json:

{
  "name": "auth-helper",
  "code": "./action-modules/auth-helper/code.js",
  "dependencies": [
    {
      "name": "axios",
      "version": "1.6.0"
    },
    {
      "name": "jsonwebtoken",
      "version": "9.0.0"
    }
  ],
  "secrets": [
    {
      "name": "JWT_SECRET",
      "value": "##JWT_SECRET##"
    }
  ]
}

Contents of auth-helper/code.js:

const jwt = require('jsonwebtoken');
const axios = require('axios');

/**
 * Auth Helper Module
 * Provides JWT validation and token refresh utilities
 */
module.exports = {
  async validateToken(token) {
    const secret = actions.secrets.JWT_SECRET;
    try {
      return jwt.verify(token, secret);
    } catch (error) {
      throw new Error('Invalid token: ' + error.message);
    }
  },

  async fetchUserData(userId) {
    const response = await axios.get(`https://api.example.com/users/${userId}`);
    return response.data;
  },
};

Using Action Modules in Actions

Actions can reference action modules in their configuration:

YAML Example:

actions:
  - name: send-phone-message
    code: ./actions/send-phone-message/code.js
    supported_triggers:
      - id: send-phone-message
        version: v1
    modules:
      - module_name: notification-helper
        module_version_number: 1

Directory Example:

Contents of actions/send-phone-message.json:

{
  "name": "send-phone-message",
  "code": "./actions/send-phone-message/code.js",
  "supported_triggers": [
    {
      "id": "send-phone-message",
      "version": "v1"
    }
  ],
  "modules": [
    {
      "module_name": "notification-helper",
      "module_version_number": 1
    }
  ]
}

The action can then import and use the module in its code:

const notificationHelper = require('actions:notification-helper');

exports.onExecuteSendPhoneMessage = async (event) => {
  const message = notificationHelper.formatMessage(
    event.user.phone_number,
    'Your verification code'
  );
};

Supplemental Signals

Supplemental signals configuration allows you to enable third-party integrations for enhanced security and risk assessment.

  • akamai_enabled (boolean): Enable processing of incoming Akamai headers for supplemental security signals

YAML Example

# Contents of ./tenant.yaml
supplementalSignals:
  akamai_enabled: true

Directory Example

Folder: ./supplemental-signals.json

{
  "akamai_enabled": true
}

For more details, see the Management API documentation.

Event Streams

Event Streams allow you to subscribe to Auth0 tenant events and forward them to external destinations (webhook, AWS EventBridge, or an Auth0 Action).

Schema Properties

  • name (string, required): Display name for the event stream.
  • status (string): enabled or disabled.
  • subscriptions (array): List of event types to subscribe to. Each entry has an event_type string (e.g. user.created, organization.member.added). If omitted, no events are forwarded.
  • destination (object, required): Destination configuration.
    • type (string): webhook, eventbridge, or action.
    • configuration (object): Destination-specific settings.

Webhook destination

{
  "type": "webhook",
  "configuration": {
    "webhook_endpoint": "https://example.com/events",
    "webhook_authorization": {
      "method": "bearer"
    }
  }
}

Supported webhook_authorization methods: basic (username only returned), bearer, custom_header. Secrets are masked on export unless AUTH0_EXPORT_SECRETS: true.

AWS EventBridge destination

{
  "type": "eventbridge",
  "configuration": {
    "aws_account_id": "123456789012",
    "aws_region": "us-east-1"
  }
}

Note: EventBridge streams cannot have their destination updated after creation. Only name, subscriptions, and status can be patched.

Action destination

{
  "type": "action",
  "configuration": {
    "action_id": "act_abc123"
  }
}

Note: like EventBridge, Action streams cannot have their destination updated after creation. Only name, subscriptions, and status can be patched — the destination is stripped from update payloads (an info message is logged when this happens).

YAML Example

# Contents of ./tenant.yaml
eventStreams:
  - name: My Webhook Stream
    status: enabled
    subscriptions:
      - event_type: user.created
      - event_type: user.deleted
    destination:
      type: webhook
      configuration:
        webhook_endpoint: https://example.com/events
        webhook_authorization:
          method: bearer

Directory Example

Folder: ./event-streams/

Each event stream is stored as a separate JSON file named after the stream (e.g. my-webhook-stream.json):

{
  "name": "My Webhook Stream",
  "status": "enabled",
  "subscriptions": [{ "event_type": "user.created" }],
  "destination": {
    "type": "webhook",
    "configuration": {
      "webhook_endpoint": "https://example.com/events",
      "webhook_authorization": {
        "method": "bearer"
      }
    }
  }
}

For more details, see the Management API documentation.

Rate Limit Policies

Rate Limit Policies allow you to control the rate at which clients can make authentication requests to the OAuth authentication API. Each policy targets a specific consumer selector (e.g. a specific client, all third-party clients, or a default fallback) and defines the action to take when the limit is exceeded.

Schema Properties

Property Type Required Description
resource string Yes The API protected by the policy. Currently only oauth_authentication_api is supported.
consumer string Yes The consumer type. Currently only client is supported.
consumer_selector string Yes Identifies the target within the consumer. Supported values: client_id:<client_id> to target a specific client, cimd_clients for all CIMD clients, third_party_clients for all third-party clients, or default as a fallback for any unmatched consumer.
configuration.action string Yes The action to take when the rate limit is exceeded. One of: allow, block, log, redirect.
configuration.limit number Required for block, log, redirect Maximum number of requests allowed in a refresh window.
configuration.redirect_uri string Required for redirect The HTTPS URI to redirect to when the rate limit is exceeded.

YAML Example

# Contents of ./tenant.yaml
rateLimitPolicies:
  - resource: oauth_authentication_api
    consumer: client
    consumer_selector: default
    configuration:
      action: block
      limit: 100

  - resource: oauth_authentication_api
    consumer: client
    consumer_selector: third_party_clients
    configuration:
      action: log
      limit: 50

  - resource: oauth_authentication_api
    consumer: client
    consumer_selector: client_id:some-client-id
    configuration:
      action: redirect
      limit: 10
      redirect_uri: https://example.com/rate-limited

Directory Example

Folder: ./rate-limit-policies/

Each rate limit policy is stored as a separate JSON file named after its consumer_selector (e.g. default.json):

{
  "resource": "oauth_authentication_api",
  "consumer": "client",
  "consumer_selector": "default",
  "configuration": {
    "action": "block",
    "limit": 100
  }
}

For more details, see the Management API documentation.

Client Credentials (Private Key JWT / mTLS)

The Deploy CLI supports managing client authentication credentials for Private Key JWT and mTLS. Credentials are child resources of clients, managed via the /clients/{id}/credentials API.

How it works

Export: client_authentication_methods is exported with credential stubs containing only name and credential_type. The pem field is never exported — Auth0 does not return it after creation. If no named credentials exist for a client, client_authentication_methods is omitted entirely from the export.

Deploy: Credential reconciliation only activates when at least one credential in the config contains a pem field. This means a plain export→deploy will never delete existing credentials — pem is the explicit opt-in signal.

  • Creates credentials present in config but missing in Auth0
  • Deletes credentials removed from config (requires AUTH0_ALLOW_DELETE=true)
  • Creates always run before deletes — Auth0 allows max 2 credentials per client, so both exist simultaneously during the rotation window
  • Re-wires client_authentication_methods with resolved credential IDs after reconciliation
  • If client_authentication_methods is absent from the client config entirely, it is treated as intentional deletion — all existing credentials are removed (requires AUTH0_ALLOW_DELETE=true)

Supported credential types

credential_type Auth method key Use case
public_key private_key_jwt Private Key JWT
x509_cert self_signed_tls_client_auth mTLS (self-signed cert)
cert_subject_dn tls_client_auth mTLS (CA-signed cert, subject DN)

Optional credential fields

Beyond name, credential_type, and pem, the following optional fields are forwarded to Auth0 when a public_key (private_key_jwt) credential is created (see the Management API docs):

Field Notes
kid Key ID. If omitted, Auth0 auto-generates one. Format: [0-9a-zA-Z-_]{10,64}
alg Signing algorithm: RS256, RS384, or PS256
expires_at ISO 8601 expiry. If omitted, the credential never expires
parse_expiry_from_cert Parse the expiry from the X509 certificate supplied in pem

Note: These fields are honored only when the credential is created (matching is by name). Changing a field such as kid on an existing credential with the same name is a no-op — rotate by adding a new credential under a new name and removing the old one. kid is not exported (Auth0 returns only name and credential_type on read).

Workflow

To add or rotate a credential:

  1. Generate a key pair:

    openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout -out public.pem

  2. Add the credential to your client config with the public key pem:

    clients:
  - name: My API Client
    client_authentication_methods:
      private_key_jwt:
        credentials:
          - name: my-key-v2
            credential_type: public_key
            kid: my-custom-kid # optional; auto-generated if omitted
            alg: RS256 # optional
            pem: |
              -----BEGIN PUBLIC KEY-----
              MIIBIjANBgkq...
              -----END PUBLIC KEY-----

  3. Deploy — the credential is created in Auth0 and client_authentication_methods is updated.

  4. To rotate: add the new key alongside the old one (both exist simultaneously), then remove the old one in a subsequent deploy.

Export shape (name and credential_type only)

clients:
  - name: My API Client
    client_authentication_methods:
      private_key_jwt:
        credentials:
          - name: my-key-v2
            credential_type: public_key

If no credentials exist for the client, client_authentication_methods is omitted entirely — not exported as an empty object.

Directory Example

./clients/
    ./My API Client.json

Contents of My API Client.json (deploy-time, with pem):

{
  "name": "My API Client",
  "client_authentication_methods": {
    "private_key_jwt": {
      "credentials": [
        {
          "name": "my-key-v2",
          "credential_type": "public_key",
          "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
        }
      ]
    }
  }
}

Note: The pem field must be supplied manually from your key generation step. Never commit private keys — only the public key PEM goes in the config.

Token Vault Privileged Access

Early Access: token_vault_privileged_access requires the token_vault_subject_type_jwt_ea_rollout feature flag to be enabled on the tenant, and writes additionally require the create:client_token_vault_privileged_access / update:client_token_vault_privileged_access scopes. This field is export-only in the Deploy CLI (see below), so these requirements affect only manual configuration on the tenant, not the CLI.

The Deploy CLI exports the token_vault_privileged_access property on clients, which hardens a privileged Token Vault worker by restricting the caller IPs, connections, and scopes it may use at runtime.

Export-only field: token_vault_privileged_access is exported for visibility but is not deployed by the Deploy CLI — it is stripped from create/update payloads. The Management API requires a credentials array (tenant-specific credential id references) whenever the object is sent, and those ids are never persisted by the CLI because they are not portable across tenants. Sending the object without them fails validation, and sending exported ids would re-send stale references on a cross-tenant deploy. Manage token_vault_privileged_access directly on the tenant.

Field Type Description
ip_allowlist array of strings IPv4/IPv6 addresses or CIDR ranges permitted to call token exchange on behalf of this client.
grants array of objects Connection/scope pin objects. Each has a connection (name) and scopes (array). Max 5 connections; max 20 scopes total.

Exported shape (credentials is stripped; ip_allowlist and grants are kept for visibility):

clients:
  - name: My Token Vault Privileged App
    app_type: non_interactive
    token_vault_privileged_access:
      ip_allowlist:
        - '192.168.1.0/24'
        - '10.0.0.1'
      grants:
        - connection: google-oauth2
          scopes:
            - 'https://www.googleapis.com/auth/calendar.readonly'
        - connection: slack
          scopes:
            - 'chat:write'
            - 'channels:read'

MFA Advanced Factor Configuration

The Deploy CLI manages the MFA (Guardian) advanced factor settings through three separate resources. Each is a single object rather than a set, so it cannot be deleted; an empty or omitted value is skipped rather than treated as a deletion. If the feature is unavailable on the tenant, the resource is skipped gracefully.

  • guardianPhoneFactorSettings: one-time password settings for the phone factor.
    • otp_length (number): number of digits in the OTP code.
    • otp_expiration_time (number): OTP validity window, in seconds.
  • guardianEmailFactorSettings: one-time password settings for the email factor, with the same fields as the phone factor.
  • guardianSettings: MFA session and "Remember Me" behavior.
    • display_remember_me_checkbox (boolean): whether to show the "Remember Me" checkbox on the MFA prompt in Universal Login.
    • remember_me_default_value (boolean): default state of that checkbox.
    • mfa_session_inactivity_timeout (number): inactivity duration, in seconds, after which the user is prompted for MFA. Cannot exceed the overall timeout.
    • mfa_session_overall_timeout (number): maximum duration, in seconds, after which the user is prompted for MFA regardless of activity.

YAML Example

# Contents of ./tenant.yaml
guardianPhoneFactorSettings:
  otp_length: 6
  otp_expiration_time: 300
guardianEmailFactorSettings:
  otp_length: 6
  otp_expiration_time: 300
guardianSettings:
  display_remember_me_checkbox: true
  remember_me_default_value: false
  mfa_session_inactivity_timeout: 604800
  mfa_session_overall_timeout: 2592000

Directory Example

Each resource is a JSON file inside the guardian folder:

// Contents of ./guardian/phoneFactorSettings.json
{
  "otp_length": 6,
  "otp_expiration_time": 300
}
// Contents of ./guardian/emailFactorSettings.json
{
  "otp_length": 6,
  "otp_expiration_time": 300
}
// Contents of ./guardian/settings.json
{
  "display_remember_me_checkbox": true,
  "remember_me_default_value": false,
  "mfa_session_inactivity_timeout": 604800,
  "mfa_session_overall_timeout": 2592000
}

For more details, see the Management API documentation.