Zitadel
@thomas/zitadelv2026.10.11.1
01README
Non-destructive administration of a Zitadel instance over its Management API (v1 REST), authenticated with a JWT private-key service account. Reads orgs, projects, applications, users and managers. Creates OIDC/API applications and machine (service) users (idempotent); manages project roles and user grants, including the role-assertion flag that puts roles in tokens; creates PATs and machine keys, rotates client secrets; and deactivates or reactivates objects. Creates machine identities only, never human users. Two methods delete, both verify-first: removing a project role (roles cannot be deactivated) and revoking a PAT. Secrets are output once and marked sensitive.
02Behaviors
@thomas/zitadelv2026.10.11.1zitadel.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Zitadel base URL / issuer, e.g. https://zitadel.example.com. Plain http |
| keyJson | string | Service-user machine key JSON (the whole blob downloaded from Zitadel; |
| orgId? | string | Target org id (x-zitadel-orgid header). Omit to use the service user's own org. |
| tokenScope? | string | OAuth scope requested for the API token (advanced). The project:id:zitadel:aud |
fn org_get()
Get the caller's organization (id/name/state/domain). Read-only.
fn project_list()
List projects (factory: one `project` per project). Read-only.
fn app_list(projectId: string)
List applications in a project with their OIDC/API config (no secrets). Read-only.
| Argument | Type | Description |
|---|---|---|
| projectId | string | Project id to list applications for |
fn app_get(projectId: string, appId: string)
Get one application's full config (no secret). Read-only.
| Argument | Type | Description |
|---|---|---|
| projectId | string | |
| appId | string |
fn oidc_app_redirect_set(projectId: string, appId: string)
Add and/or remove redirect URIs on an OIDC app's allowlist via read-modify-
| Argument | Type | Description |
|---|---|---|
| projectId | string | Project id (from app_list / project_list) |
| appId | string | Application id (from app_list) |
fn user_list(type?: enum)
List users, optionally filtered by type (factory: one `user` each). Read-only.
| Argument | Type | Description |
|---|---|---|
| type? | enum | Filter by user type |
fn manager_audit()
List org managers (members) and their roles: who can administer this org. Read-only.
fn project_ensure(name: string)
Find-or-create a project by name. Idempotent.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name (find-or-create by exact name) |
fn oidc_app_ensure(project: string, name: string, appType?: enum, authMethod?: enum, accessTokenType?: enum, devMode?: boolean)
Ensure an OIDC application: find-or-create by name within the project
| Argument | Type | Description |
|---|---|---|
| project | string | Project name (created if absent) or project id |
| name | string | Application name (find-or-create within the project) |
| appType? | enum | |
| authMethod? | enum | OIDC client auth method. Use `none` for public PKCE (SPA/native). |
| accessTokenType? | enum | |
| devMode? | boolean | Relax redirect-URI checks (non-https/localhost). Test only. |
fn api_app_ensure(project: string, name: string, authMethod?: enum)
Find-or-create an API application (resource server / M2M) by name
| Argument | Type | Description |
|---|---|---|
| project | string | |
| name | string | |
| authMethod? | enum |
fn app_secret_rotate(projectId: string, appId: string, kind?: enum)
Regenerate an application's client secret. Reads the app first and
| Argument | Type | Description |
|---|---|---|
| projectId | string | |
| appId | string | |
| kind? | enum | Optional check: the method refuses if the app is not of this kind |
fn machine_user_ensure(username: string, name: string, description?: string, accessTokenType?: enum)
Find-or-create a machine (service) user by username. Idempotent.
| Argument | Type | Description |
|---|---|---|
| username | string | Login name (find-or-create) |
| name | string | Display name |
| description? | string | |
| accessTokenType? | enum |
fn pat_create(user: string, expirationDate?: string)
Add a personal access token to a machine user. Returns the token once.
| Argument | Type | Description |
|---|---|---|
| user | string | Machine user id or username |
| expirationDate? | string | RFC3339 expiry, e.g. 2027-01-01T00:00:00Z (omit for none) |
fn pat_revoke(user: string, tokenId: string)
Revoke a PAT. Verify-first: confirms the tokenId belongs to the user before deleting.
| Argument | Type | Description |
|---|---|---|
| user | string | Machine user id or username |
| tokenId | string | PAT id to revoke (verified to belong to the user first) |
fn machine_key_create(user: string, expirationDate?: string)
Add a JSON private key to a machine user. Returns the downloadable key JSON once.
| Argument | Type | Description |
|---|---|---|
| user | string | Machine user id or username |
| expirationDate? | string |
fn machine_secret_generate(user: string)
Generate (rotate) a machine user's client secret. Returns the secret once.
| Argument | Type | Description |
|---|---|---|
| user | string | Machine user id or username |
fn app_set_state(projectId: string, appId: string, state: enum)
Deactivate or reactivate an application (reversible; verify-first; idempotent). No hard delete.
| Argument | Type | Description |
|---|---|---|
| projectId | string | |
| appId | string | |
| state | enum |
fn user_set_state(userId: string, state: enum)
Deactivate or reactivate a user (reversible; verify-first; idempotent).
| Argument | Type | Description |
|---|---|---|
| userId | string | |
| state | enum |
fn role_list(projectId: string)
List a project's roles (factory: one `role` each). Read-only.
| Argument | Type | Description |
|---|---|---|
| projectId | string | Project id to list roles for |
fn role_ensure(project: string, key: string, displayName?: string, group?: string)
Find-or-create a project role by key; converge displayName/group. Idempotent.
| Argument | Type | Description |
|---|---|---|
| project | string | Project name (created if absent) or project id |
| key | string | Role key (stable identifier; find-or-create) |
| displayName? | string | Human-readable role name |
| group? | string | Optional grouping label for the role |
fn role_remove(projectId: string, key: string)
Remove a project role (verify-first DELETE). Roles have no deactivate
| Argument | Type | Description |
|---|---|---|
| projectId | string | |
| key | string | Role key to remove (verified to exist first) |
fn grant_list(user?: string, projectId?: string)
List user grants (which roles users hold on which projects), optionally
| Argument | Type | Description |
|---|---|---|
| user? | string | Filter by user id or login name (omit for all users) |
| projectId? | string | Filter by project id (omit for all projects) |
fn grant_ensure(user: string, project: string)
Grant a user a set of roles on a project (find-or-create by user+project;
| Argument | Type | Description |
|---|---|---|
| user | string | User id or login name (e.g. alice@example.com) to grant roles to |
| project | string | Project name or project id (the project must exist) |
fn grant_set_state(user: string, grantId: string, state: enum)
Deactivate or reactivate a user grant (reversible; verify-first; idempotent). No hard delete.
| Argument | Type | Description |
|---|---|---|
| user | string | User id or login name the grant belongs to |
| grantId | string | Grant id (verified to belong to the user first) |
| state | enum |
fn project_authz_set(project: string, roleAssertion?: boolean, roleCheck?: boolean, hasProjectCheck?: boolean)
Set the authorization flags on an existing project (roleAssertion /
| Argument | Type | Description |
|---|---|---|
| project | string | Project name or project id |
| roleAssertion? | boolean | Assert project roles into tokens/userinfo (the flag that surfaces grants) |
| roleCheck? | boolean | Require a project role to authenticate |
| hasProjectCheck? | boolean | Require the user's org to have the project granted |
Resources
org(infinite)— An organization record
project(infinite)— A project record / ensure result
app(infinite)— An application record (config only; never a secret)
oidc-redirect-result(infinite)— Result of an oidc_app_redirect_set change
app-credential(infinite)— Result of creating/rotating an app (clientId + clientSecret once)
user(infinite)— A user record / ensure result
machine-credential(infinite)— Result of minting a machine credential (PAT / key / secret); secret once
manager(infinite)— An org manager (member) and their roles
role(infinite)— A project role (key/displayName/group)
grant(infinite)— A user grant: which roles a user holds on a project
state-result(infinite)— Result of a reversible deactivate/reactivate
03Previous Versions
2026.06.24.1
Removed 1 behaviors
2026.06.04.2
2026.06.04.1
04Stats
A
93 / 100
Downloads
33
Archive size
41.1 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License1/2partial
no SPDX license declared
- Verified public repository2/2earned
credentials-sensitive-field1 accepted
A field that looks like a secret but is not marked sensitive, so its value is not vaulted.
- models/zitadel.ts:65 — no reason given
06Platforms
07Labels