KosmoKrator

productivity

Auth0 Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Auth0 KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.auth_zero.*. Use lua_read_doc("integrations.auth-zero") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Auth0 workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.auth_zero.list_users({page = 1, per_page = 1, q = "example_q", sort = "example_sort"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("auth-zero"))' --json
kosmo integrations:lua --eval 'print(docs.read("auth-zero.list_users"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local auth_zero = app.integrations.auth_zero
local result = auth_zero.list_users({page = 1, per_page = 1, q = "example_q", sort = "example_sort"})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.auth_zero, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.auth_zero.default.* or app.integrations.auth_zero.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Auth0, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Auth0 — Lua API Supplement

Namespace: app.integrations["auth-zero"]

This integration targets the Auth0 Management API v2. Configure a tenant domain such as tenant.us.auth0.com and a Management API access token whose audience is https://tenant.us.auth0.com/api/v2/.

Users

local users = app.integrations["auth-zero"].list_users({
  per_page = 25,
  q = 'email:*@example.test',
  sort = "created_at:-1"
})

local user = app.integrations["auth-zero"].get_user({
  id = "auth0|507f1f77bcf86cd799439010"
})

local created = app.integrations["auth-zero"].create_user({
  email = "jane@example.test",
  password = "fake-password-123",
  connection = "Username-Password-Authentication",
  name = "Jane Example"
})

create_user requires Auth0 scopes such as create:users and only works for connections where the token is allowed to create users.

Tenant Metadata

local connections = app.integrations["auth-zero"].list_connections({
  strategy = "auth0"
})

local roles = app.integrations["auth-zero"].list_roles({
  page = 0,
  per_page = 50
})

local settings = app.integrations["auth-zero"].get_tenant_settings({})

Health Check

The historical get_current_user tool now performs a Management API health check by retrieving tenant settings. Management API tokens are commonly machine-to-machine tokens and do not reliably map to a /users/me profile.

local health = app.integrations["auth-zero"].get_current_user({})
print(health._health_check)

Multi-Account Usage

app.integrations["auth-zero"].list_users({...})
app.integrations["auth-zero"].default.list_users({...})
app.integrations["auth-zero"].production.list_users({...})
Raw agent markdown 
# Auth0 — Lua API Supplement

Namespace: `app.integrations["auth-zero"]`

This integration targets the Auth0 Management API v2. Configure a tenant domain such as `tenant.us.auth0.com` and a Management API access token whose audience is `https://tenant.us.auth0.com/api/v2/`.

## Users

```lua
local users = app.integrations["auth-zero"].list_users({
  per_page = 25,
  q = 'email:*@example.test',
  sort = "created_at:-1"
})

local user = app.integrations["auth-zero"].get_user({
  id = "auth0|507f1f77bcf86cd799439010"
})

local created = app.integrations["auth-zero"].create_user({
  email = "jane@example.test",
  password = "fake-password-123",
  connection = "Username-Password-Authentication",
  name = "Jane Example"
})
```

`create_user` requires Auth0 scopes such as `create:users` and only works for connections where the token is allowed to create users.

## Tenant Metadata

```lua
local connections = app.integrations["auth-zero"].list_connections({
  strategy = "auth0"
})

local roles = app.integrations["auth-zero"].list_roles({
  page = 0,
  per_page = 50
})

local settings = app.integrations["auth-zero"].get_tenant_settings({})
```

## Health Check

The historical `get_current_user` tool now performs a Management API health check by retrieving tenant settings. Management API tokens are commonly machine-to-machine tokens and do not reliably map to a `/users/me` profile.

```lua
local health = app.integrations["auth-zero"].get_current_user({})
print(health._health_check)
```

## Multi-Account Usage

```lua
app.integrations["auth-zero"].list_users({...})
app.integrations["auth-zero"].default.list_users({...})
app.integrations["auth-zero"].production.list_users({...})
```
Metadata-derived Lua example 
local result = app.integrations.auth_zero.list_users({page = 1, per_page = 1, q = "example_q", sort = "example_sort"})
print(result)

Functions

list_users Read

List users in the Auth0 tenant. Supports search with Lucene syntax, pagination, and sorting.

Lua path
app.integrations.auth_zero.list_users
Full name
auth-zero.auth_zero_list_users
ParameterTypeRequiredDescription
page integer no Page index (zero-based). Default: 0.
per_page integer no Number of results per page. Default: 50, max: 100.
q string no Lucene search query (e.g. "email:*@example.com").
sort string no Field to sort by, with optional direction (e.g. "created_at:-1" or "name:1").
get_user Read

Retrieve a single Auth0 user by their user ID (e.g. "auth0|abc123").

Lua path
app.integrations.auth_zero.get_user
Full name
auth-zero.auth_zero_get_user
ParameterTypeRequiredDescription
id string yes The Auth0 user identifier (e.g. "auth0|abc123", "google-oauth2|xyz").
create_user Write

Create a new user in Auth0. Requires email, password, and the connection name (database connection).

Lua path
app.integrations.auth_zero.create_user
Full name
auth-zero.auth_zero_create_user
ParameterTypeRequiredDescription
email string yes Email address for the new user.
password string yes Password for the new user (must meet connection requirements).
connection string yes The database connection name to create the user in (e.g. "Username-Password-Authentication").
name string no Full name of the user.
list_connections Read

List identity connections configured in the Auth0 tenant. Optionally filter by strategy (e.g. "auth0", "google-oauth2").

Lua path
app.integrations.auth_zero.list_connections
Full name
auth-zero.auth_zero_list_connections
ParameterTypeRequiredDescription
strategy string no Filter by connection strategy (e.g. "auth0", "google-oauth2", "samlp", "oidc").
list_roles Read

List roles defined in the Auth0 tenant with optional pagination.

Lua path
app.integrations.auth_zero.list_roles
Full name
auth-zero.auth_zero_list_roles
ParameterTypeRequiredDescription
page integer no Page index (zero-based). Default: 0.
per_page integer no Number of results per page. Default: 50.
get_tenant_settings Read

Retrieve the Auth0 tenant settings (session lifetime, idle timeout, default directory, etc.).

Lua path
app.integrations.auth_zero.get_tenant_settings
Full name
auth-zero.auth_zero_get_tenant_settings
ParameterTypeRequiredDescription
No parameters.
health_check Read

Run a lightweight Auth0 Management API health check by retrieving tenant settings.

Lua path
app.integrations.auth_zero.health_check
Full name
auth-zero.auth_zero_get_current_user
ParameterTypeRequiredDescription
No parameters.