KosmoKrator

productivity

Clerk Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.clerk.*. Use lua_read_doc("integrations.clerk") 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 Clerk workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.clerk.api_get({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("clerk"))' --json
kosmo integrations:lua --eval 'print(docs.read("clerk.api_get"))' --json

Workflow file

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

workflow.lua 
local clerk = app.integrations.clerk
local result = clerk.api_get({})

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.clerk, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.clerk.default.* or app.integrations.clerk.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Clerk, 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.

Clerk

Clerk tools are exposed under app.integrations.clerk. The integration uses Clerk’s Backend API with a secret key. Do not use publishable keys.

Raw API Helpers

Use raw helpers for Backend API endpoints that do not yet have a first-class tool:

  • clerk_api_get
  • clerk_api_post
  • clerk_api_patch
  • clerk_api_delete

Paths are relative to https://api.clerk.com/v1.

local sessions = app.integrations.clerk.clerk_api_get({
  path = "/sessions",
  query = {
    user_id = "user_123"
  }
})

Users

local users = app.integrations.clerk.clerk_list_users({
  query = "alex",
  limit = 20
})

local user = app.integrations.clerk.clerk_get_user({
  id = "user_123"
})

User tools include:

  • clerk_list_users
  • clerk_count_users
  • clerk_get_user
  • clerk_create_user
  • clerk_update_user
  • clerk_delete_user
  • clerk_ban_user
  • clerk_unban_user
  • clerk_lock_user
  • clerk_unlock_user

The existing user create/update tools keep their compatibility argument names. New endpoint-mapped tools use user_id.

Sessions

local active = app.integrations.clerk.clerk_list_sessions({
  user_id = "user_123",
  status = "active"
})

app.integrations.clerk.clerk_revoke_session({
  session_id = "sess_123"
})

Session tools:

  • clerk_list_sessions
  • clerk_get_session
  • clerk_revoke_session

Organizations

local org = app.integrations.clerk.clerk_create_organization({
  name = "Example Inc",
  created_by = "user_123"
})

app.integrations.clerk.clerk_create_organization_membership({
  organization_id = "org_123",
  user_id = "user_123",
  role = "org:member"
})

Organization tools:

  • clerk_list_organizations
  • clerk_create_organization
  • clerk_get_organization
  • clerk_update_organization
  • clerk_delete_organization
  • clerk_list_organization_memberships
  • clerk_create_organization_membership
  • clerk_update_organization_membership
  • clerk_delete_organization_membership
  • clerk_list_organization_invitations
  • clerk_create_organization_invitation
  • clerk_revoke_organization_invitation

Organization invitation creation is rate limited by Clerk. The tool forwards Clerk API errors directly.

Application Invitations And Sign-In Tokens

local invitation = app.integrations.clerk.clerk_create_invitation({
  email_address = "person@example.test",
  redirect_url = "https://example.test/welcome"
})

Available tools:

  • clerk_list_invitations
  • clerk_create_invitation
  • clerk_revoke_invitation
  • clerk_create_sign_in_token
  • clerk_revoke_sign_in_token

Output Shape

Most tools return Clerk’s parsed JSON response directly. Existing compatibility tools such as clerk_get_current_user keep their normalized health-check response.

Raw agent markdown 
# Clerk

Clerk tools are exposed under `app.integrations.clerk`. The integration uses Clerk's Backend API with a secret key. Do not use publishable keys.

## Raw API Helpers

Use raw helpers for Backend API endpoints that do not yet have a first-class tool:

- `clerk_api_get`
- `clerk_api_post`
- `clerk_api_patch`
- `clerk_api_delete`

Paths are relative to `https://api.clerk.com/v1`.

```lua
local sessions = app.integrations.clerk.clerk_api_get({
  path = "/sessions",
  query = {
    user_id = "user_123"
  }
})
```

## Users

```lua
local users = app.integrations.clerk.clerk_list_users({
  query = "alex",
  limit = 20
})

local user = app.integrations.clerk.clerk_get_user({
  id = "user_123"
})
```

User tools include:

- `clerk_list_users`
- `clerk_count_users`
- `clerk_get_user`
- `clerk_create_user`
- `clerk_update_user`
- `clerk_delete_user`
- `clerk_ban_user`
- `clerk_unban_user`
- `clerk_lock_user`
- `clerk_unlock_user`

The existing user create/update tools keep their compatibility argument names. New endpoint-mapped tools use `user_id`.

## Sessions

```lua
local active = app.integrations.clerk.clerk_list_sessions({
  user_id = "user_123",
  status = "active"
})

app.integrations.clerk.clerk_revoke_session({
  session_id = "sess_123"
})
```

Session tools:

- `clerk_list_sessions`
- `clerk_get_session`
- `clerk_revoke_session`

## Organizations

```lua
local org = app.integrations.clerk.clerk_create_organization({
  name = "Example Inc",
  created_by = "user_123"
})

app.integrations.clerk.clerk_create_organization_membership({
  organization_id = "org_123",
  user_id = "user_123",
  role = "org:member"
})
```

Organization tools:

- `clerk_list_organizations`
- `clerk_create_organization`
- `clerk_get_organization`
- `clerk_update_organization`
- `clerk_delete_organization`
- `clerk_list_organization_memberships`
- `clerk_create_organization_membership`
- `clerk_update_organization_membership`
- `clerk_delete_organization_membership`
- `clerk_list_organization_invitations`
- `clerk_create_organization_invitation`
- `clerk_revoke_organization_invitation`

Organization invitation creation is rate limited by Clerk. The tool forwards Clerk API errors directly.

## Application Invitations And Sign-In Tokens

```lua
local invitation = app.integrations.clerk.clerk_create_invitation({
  email_address = "person@example.test",
  redirect_url = "https://example.test/welcome"
})
```

Available tools:

- `clerk_list_invitations`
- `clerk_create_invitation`
- `clerk_revoke_invitation`
- `clerk_create_sign_in_token`
- `clerk_revoke_sign_in_token`

## Output Shape

Most tools return Clerk's parsed JSON response directly. Existing compatibility tools such as `clerk_get_current_user` keep their normalized health-check response.
Metadata-derived Lua example 
local result = app.integrations.clerk.api_get({})
print(result)

Functions

api_get Read

Execute a raw Clerk Backend API GET request.

Lua path
app.integrations.clerk.api_get
Full name
clerk.clerk_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Execute a raw Clerk Backend API POST request.

Lua path
app.integrations.clerk.api_post
Full name
clerk.clerk_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Execute a raw Clerk Backend API PATCH request.

Lua path
app.integrations.clerk.api_patch
Full name
clerk.clerk_api_patch
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Execute a raw Clerk Backend API DELETE request.

Lua path
app.integrations.clerk.api_delete
Full name
clerk.clerk_api_delete
ParameterTypeRequiredDescription
No parameters.
list_users Read

List users from Clerk with optional filtering and pagination. Returns user IDs, emails, names, and profile details.

Lua path
app.integrations.clerk.list_users
Full name
clerk.clerk_list_users
ParameterTypeRequiredDescription
limit integer no Maximum number of users to return (default: 10, max: 500).
offset integer no Number of users to skip for pagination.
email_address string no Filter users by email address.
phone_number string no Filter users by phone number.
query string no Search query to filter users by name, email, or username.
order_by string no Sort order for results. Use "+created_at" for ascending or "-created_at" for descending (default: "+created_at").
count_users Read

Count Clerk users with optional filters.

Lua path
app.integrations.clerk.count_users
Full name
clerk.clerk_count_users
ParameterTypeRequiredDescription
No parameters.
get_user Read

Retrieve a single Clerk user by their user ID. Returns full profile details including email, name, and metadata.

Lua path
app.integrations.clerk.get_user
Full name
clerk.clerk_get_user
ParameterTypeRequiredDescription
id string yes The Clerk user ID (e.g., "user_2abc123").
create_user Write

Create a new user in Clerk. Requires at least one email address. Optionally set name, password, and username.

Lua path
app.integrations.clerk.create_user
Full name
clerk.clerk_create_user
ParameterTypeRequiredDescription
email_address array yes Array of email addresses for the user. At least one is required.
first_name string no The user's first name.
last_name string no The user's last name.
password string no The user's password. Minimum 8 characters.
username string no The user's username.
update_user Write

Update an existing Clerk user's profile. Provide the user ID and fields to update.

Lua path
app.integrations.clerk.update_user
Full name
clerk.clerk_update_user
ParameterTypeRequiredDescription
id string yes The Clerk user ID to update (e.g., "user_2abc123").
first_name string no Updated first name.
last_name string no Updated last name.
username string no Updated username.
delete_user Write

Delete a user from Clerk. This action is irreversible and will remove all associated data.

Lua path
app.integrations.clerk.delete_user
Full name
clerk.clerk_delete_user
ParameterTypeRequiredDescription
id string yes The Clerk user ID to delete (e.g., "user_2abc123").
ban_user Write

Ban a Clerk user.

Lua path
app.integrations.clerk.ban_user
Full name
clerk.clerk_ban_user
ParameterTypeRequiredDescription
No parameters.
unban_user Write

Unban a Clerk user.

Lua path
app.integrations.clerk.unban_user
Full name
clerk.clerk_unban_user
ParameterTypeRequiredDescription
No parameters.
lock_user Write

Lock a Clerk user.

Lua path
app.integrations.clerk.lock_user
Full name
clerk.clerk_lock_user
ParameterTypeRequiredDescription
No parameters.
unlock_user Write

Unlock a Clerk user.

Lua path
app.integrations.clerk.unlock_user
Full name
clerk.clerk_unlock_user
ParameterTypeRequiredDescription
No parameters.
list_sessions Read

List Clerk sessions.

Lua path
app.integrations.clerk.list_sessions
Full name
clerk.clerk_list_sessions
ParameterTypeRequiredDescription
No parameters.
get_session Read

Get a Clerk session.

Lua path
app.integrations.clerk.get_session
Full name
clerk.clerk_get_session
ParameterTypeRequiredDescription
No parameters.
revoke_session Write

Revoke a Clerk session.

Lua path
app.integrations.clerk.revoke_session
Full name
clerk.clerk_revoke_session
ParameterTypeRequiredDescription
No parameters.
list_organizations Read

List organizations from Clerk with optional filtering and pagination. Returns organization IDs, names, and metadata.

Lua path
app.integrations.clerk.list_organizations
Full name
clerk.clerk_list_organizations
ParameterTypeRequiredDescription
limit integer no Maximum number of organizations to return (default: 10, max: 500).
offset integer no Number of organizations to skip for pagination.
query string no Search query to filter organizations by name.
create_organization Write

Create a Clerk organization.

Lua path
app.integrations.clerk.create_organization
Full name
clerk.clerk_create_organization
ParameterTypeRequiredDescription
No parameters.
get_organization Read

Get a Clerk organization.

Lua path
app.integrations.clerk.get_organization
Full name
clerk.clerk_get_organization
ParameterTypeRequiredDescription
No parameters.
update_organization Write

Update a Clerk organization.

Lua path
app.integrations.clerk.update_organization
Full name
clerk.clerk_update_organization
ParameterTypeRequiredDescription
No parameters.
delete_organization Write

Delete a Clerk organization.

Lua path
app.integrations.clerk.delete_organization
Full name
clerk.clerk_delete_organization
ParameterTypeRequiredDescription
No parameters.
list_organization_memberships Read

List memberships for a Clerk organization.

Lua path
app.integrations.clerk.list_organization_memberships
Full name
clerk.clerk_list_organization_memberships
ParameterTypeRequiredDescription
No parameters.
create_organization_membership Write

Add a user to a Clerk organization.

Lua path
app.integrations.clerk.create_organization_membership
Full name
clerk.clerk_create_organization_membership
ParameterTypeRequiredDescription
No parameters.
update_organization_membership Write

Update a Clerk organization membership.

Lua path
app.integrations.clerk.update_organization_membership
Full name
clerk.clerk_update_organization_membership
ParameterTypeRequiredDescription
No parameters.
delete_organization_membership Write

Remove a user from a Clerk organization.

Lua path
app.integrations.clerk.delete_organization_membership
Full name
clerk.clerk_delete_organization_membership
ParameterTypeRequiredDescription
No parameters.
list_organization_invitations Read

List invitations for a Clerk organization.

Lua path
app.integrations.clerk.list_organization_invitations
Full name
clerk.clerk_list_organization_invitations
ParameterTypeRequiredDescription
No parameters.
create_organization_invitation Write

Create an invitation for a Clerk organization.

Lua path
app.integrations.clerk.create_organization_invitation
Full name
clerk.clerk_create_organization_invitation
ParameterTypeRequiredDescription
No parameters.
revoke_organization_invitation Write

Revoke a Clerk organization invitation.

Lua path
app.integrations.clerk.revoke_organization_invitation
Full name
clerk.clerk_revoke_organization_invitation
ParameterTypeRequiredDescription
No parameters.
list_invitations Read

List Clerk application invitations.

Lua path
app.integrations.clerk.list_invitations
Full name
clerk.clerk_list_invitations
ParameterTypeRequiredDescription
No parameters.
create_invitation Write

Create a Clerk application invitation.

Lua path
app.integrations.clerk.create_invitation
Full name
clerk.clerk_create_invitation
ParameterTypeRequiredDescription
No parameters.
revoke_invitation Write

Revoke a Clerk application invitation.

Lua path
app.integrations.clerk.revoke_invitation
Full name
clerk.clerk_revoke_invitation
ParameterTypeRequiredDescription
No parameters.
create_sign_token Write

Create a Clerk sign-in token.

Lua path
app.integrations.clerk.create_sign_token
Full name
clerk.clerk_create_sign_in_token
ParameterTypeRequiredDescription
No parameters.
revoke_sign_token Write

Revoke a Clerk sign-in token.

Lua path
app.integrations.clerk.revoke_sign_token
Full name
clerk.clerk_revoke_sign_in_token
ParameterTypeRequiredDescription
No parameters.
health_check Read

Health check - verify Clerk API connectivity by fetching the first user. Returns a single user or empty result to confirm the API is reachable.

Lua path
app.integrations.clerk.health_check
Full name
clerk.clerk_get_current_user
ParameterTypeRequiredDescription
No parameters.