A command line tool for checking configuration of your Auth0 tenant
npm install @auth0/auth0-checkmateCheckMate for Auth0 is a command-line utility that performs configuration checks on your Auth0 tenant. It helps ensure your tenant is securely and correctly configured by validating key settings and generating a detailed report.
---
- Validates your Auth0 tenant configuration
- Generates comprehensive audit reports
- Simple and intuitive CLI interface
---
This tool makes use of the Auth0 Management API, which consumes your tenant’s rate limits. Use it thoughtfully to avoid throttling.
CheckMate for Auth0 is designed to provide visibility into its behavior through your Auth0 tenant's log events. Tracking its use is important for monitoring and debugging purposes. You can track its use in several ways, including:
- The User-Agent string in the HTTP request header, which will have a value in the form of ${packageName}/${packageVersion} (e.g. @auth0/auth0-checkmate/1.4.0). Keep in mind that if the User-Agent string is modified on the client side, then CheckMate for Auth0 usage cannot be tracked this way.
- The client_name and scopes assigned to CheckMate when configuring initial access
- seccft events (Successful exchange of Access Token for a Client Credentials Grant) in Auth0 logs
As an example, CheckMate activity might result in a log entry like the one shown below. Each field in the log entry provides valuable information for troubleshooting or auditing, such as the client_name identifying the application, the scope showing granted permissions, and the user_agent indicating the tool version used.
``json`
{
"date": "2025-08-05T19:19:43.071Z",
"type": "seccft",
"description": "Client Credentials for Access Token",
"connection_id": "",
"client_id": "{CHECKMATE_CLIENT_ID}",
"client_name": "{CHECKMATE_CLIENT_NAME}",
"ip": "{REQUEST_IP}",
"client_ip": "{REQUEST_IP}",
"user_agent": "{CHECKMATE_USER_AGENT}",
"hostname": "{TENANT_HOSTNAME}",
"user_id": "",
"user_name": "",
"audience": "https://{TENANT_HOSTNAME}/api/v2/",
"scope": "{CHECKMATE_SCOPES}",
"$event_schema": {
"version": "1.0.0"
},
"environment_name": "{AUTH0_ENVIRONMENT}",
"log_id": "{LOG_ID}",
"tenant_name": "{AUTH0_TENANT}",
"_id": "{ID}",
"isMobile": false,
"location_info": {},
"id": "{ID}"
}
---
- Node.js v20.18.3 or higher
- A valid Auth0 tenant
---
Install CheckMate for Auth0 globally to use it as a standalone CLI tool:
`bash`
npm install -g @auth0/auth0-checkmate
Then run it with:
`bash`
a0checkmate
Follow the interactive prompts to get started.
To update CheckMate:
`bash`
npm update -g @auth0/auth0-checkmate
---
1. Clone the repository:
`bash`
git clone https://github.com/auth0/auth0-checkmate
2. Navigate into the project folder:
`bash`
cd auth0-checkmate
3. Install dependencies:
`bash`
npm install
4. Run the tool:
`bash`
npm start
---
To use CheckMate for Auth0, you need a dedicated Auth0 Application to authorize calls to the Management API.
1. In the Auth0 Dashboard, go to:
Applications → Applications
2. Click “Create Application”
3. In the setup form:
- Name: Auth0 CheckMate (or similar)Machine to Machine Applications
- Application Type:
- Click “Create”
4. On the "Authorize Machine to Machine Application" screen:
- Select Auth0 Management API
- Grant only the following scopes:
`text`
read:tenant_settings
read:custom_domains
read:prompts
read:clients
read:connections
read:connections_options
read:resource_servers
read:client_grants
read:roles
read:branding
read:email_provider
read:email_templates
read:phone_providers
read:phone_templates
read:shields
read:attack_protection
read:self_service_profiles
read:guardian_factors
read:mfa_policies
read:actions
read:log_streams
read:logs
read:network_acls
read:event_streams
read:hooks
read:rules
5. Click “Authorize” to complete setup.
6. Optional: the following environment variables can be used to provide a CI friendly configuration
`text``
AUTH0CHECKMATE_DISABLE_PDF_REPORTING=true|false
AUTH0CHECKMATE_DOMAIN=your_domain
AUTH0CHECKMATE_CLIENT_ID=your_client_id
AUTH0CHECKMATE_CLIENT_SECRET=your_client_secret
AUTH0CHECKMATE_FILE_PATH="./reports"
AUTH0CHECKMATE_SHOW_VALIDATORS=false
---
With your Auth0 application configured and the CLI installed, you’re ready to run CheckMate for Auth0 and ensure your tenant setup is secure and complete.