Zitadel

@dataverket/zitadelv2026.10.05.1· 1d agoMODELS

01README

Zitadel for swamp, over its API: seven model types, one per resource, with the whole life cycle of each. @dataverket/zitadel/project lists, reads, creates, renames, deactivates and deletes projects, and defines their roles. @dataverket/zitadel/app covers a project's applications: OIDC clients and API resource servers, their configuration, a careful redirect-allowlist change that cannot clobber the rest of a shared client, client-secret rotation, application keys, and deactivate or delete. @dataverket/zitadel/user is human and machine users over the v2 user service: find-or-create, update, deactivate, lock, delete, personal access tokens, keys, client secrets, metadata, and a password reset that mints a link rather than taking a password. @dataverket/zitadel/grant is the roles a user holds on a project, and @dataverket/zitadel/org reads the organizations and their managers. @dataverket/zitadel/action covers v2 actions: the targets an instance calls out to, their signing and public keys, and the executions that bind a condition — a request, a response, an event or a named function — to the targets it calls, with a catalog method that says which conditions this instance will accept. @dataverket/zitadel/settings reads the login, lockout, password, branding, domain, legal and security settings in force for an organization or the instance, each saying whether it is the organization's own or inherited, and writes the two that v2 exposes. Projects also carry their grants to other organizations, and the members who administer them; users carry their authentication factors and identity-provider links, which is what "does this person actually have MFA" is asked with. Every hard delete re-reads the resource first, refuses unless a confirm argument repeats its live name, and takes dryRun; deactivating stays the reversible path and the docs say so. Every secret the extension mints — client secret, token, key JSON, reset code — is emitted exactly once into a spec marked sensitive, so swamp vaults it and it never reaches a log. Authentication is a JWT private-key service account: the key is named by the definition, as a vault value (keyJson) or as a file read at call time (keyJsonFile), and exchanged per run for a short-lived token. Users speak the v2 API, which is the supported surface on Zitadel v4; projects, applications, roles and grants speak v1 Management, where v2 is still beta. Forked from @thomas/zitadel (MIT, copyright Thomas Elliott), which is one type and machine identities only, and widened to full CRUD across five types.

02Models7

@dataverket/zitadel/orgv2026.10.05.1org.ts

fn get()

Read the service user's own organization and store it. Read-only.

fn list()

List every organization the service user can see and store each one. Read-only.

fn managerList()

List the managers of the service user's organization with their roles — who can administer it. Read-only.

Resources

org(infinite)— An organization on the instance

manager(infinite)— An organization manager and the manager roles they hold

@dataverket/zitadel/projectv2026.10.05.1project.ts

fn list()

List every project in the organization and store each one. Read-only.

fn get()

Read one project by id or name and store it. Read-only.

fn ensure(name: string, roleAssertion?: boolean, roleCheck?: boolean, hasProjectCheck?: boolean)

Find or create a project by name, converging any flags given. Idempotent.

Argument	Type	Required	Description
name	string	yes	Project name; an existing project of this name is reused
roleAssertion?	boolean	no	Assert the user's roles into tokens and the userinfo endpoint
roleCheck?	boolean	no	Require a role of this project for a user to log in
hasProjectCheck?	boolean	no	Require the user's organization to be granted this project

fn update(name?: string, roleAssertion?: boolean, roleCheck?: boolean, hasProjectCheck?: boolean)

Rename a project or change its authorization flags, leaving the rest as it is. Idempotent.

Argument	Type	Required	Description
name?	string	no	New project name
roleAssertion?	boolean	no
roleCheck?	boolean	no
hasProjectCheck?	boolean	no

fn setState(state: enum)

Deactivate or reactivate a project. Reversible, and a no-op when it is already in that state.

Argument	Type	Required	Description
state	enum	yes	Target state; the change is reversible either way

fn delete(confirm: string)

Delete a project and everything under it — applications, roles and grants. Verify-first: confirm must repeat the live name, and dryRun only reports. Prefer setState inactive, which is reversible.

Argument	Type	Required	Description
confirm	string	yes	The project's exact name, repeated — a mismatch refuses the delete

fn roleList()

List a project's roles and store each one. Read-only.

fn roleEnsure(displayName?: string, group?: string)

Find or create a project role by key, converging its display name and group. Idempotent.

Argument	Type	Required	Description
displayName?	string	no	Human-readable role name
group?	string	no	Group the role belongs to

fn roleRemove()

Remove a project role. Verify-first, and dryRun only reports. A role has no deactivated state, so this is a delete: it also revokes the grants that reference the role.

fn projectGrantList()

List the organizations this project has been granted to, with the roles each one got. Read-only.

fn projectGrantEnsure()

Grant this project to another organization with exactly these roles, creating the grant when it is missing and converging the role set when it is not. Idempotent.

fn projectGrantSetState(state: enum)

Deactivate or reactivate a project grant. Reversible, and a no-op when it is already in that state.

Argument	Type	Required	Description
state	enum	yes

fn projectGrantDelete(confirm: string)

Take a project grant back from another organization, which revokes every authorization their users held through it. Verify-first: confirm must repeat the granted organization's name, and dryRun only reports. Prefer projectGrantSetState inactive, which is reversible.

Argument	Type	Required	Description
confirm	string	yes	The granted organization's exact name, or its id when it has no name —

fn projectGrantMemberList()

List the users of the granted organization who may administer a project grant. Read-only.

fn projectGrantMemberEnsure(userId: string)

Give a user of the granted organization these manager roles on the grant, adding the membership when it is missing and converging the roles when it is not. Idempotent.

Argument	Type	Required	Description
userId	string	yes	A user of the granted organization

fn projectGrantMemberRemove(userId: string)

Take a user's manager roles on a project grant away, verifying the membership exists first. dryRun only reports; the user keeps their account and any other authorization.

Argument	Type	Required	Description
userId	string	yes

Resources

project(infinite)— A project

role(infinite)— A role defined by a project

project-grant(infinite)— A project granted to another organization

project-grant-member(infinite)— A user of the granted organization who may administer the grant

state(infinite)— The outcome of a reversible state change

deletion(infinite)— The outcome of a delete, or of a dry run that planned one

@dataverket/zitadel/appv2026.10.05.1app.ts

fn list()

List a project's applications with their configuration and store each one. Read-only, no secrets.

fn get()

Read one application's full configuration and store it. Read-only, no secret.

fn ensureOidc(name: string, appType: enum, authMethod: enum, accessTokenType: enum, loginVersion: enum, loginBaseUri?: string)

Find or create an OIDC application in a project and converge its whole OIDC configuration to what is given here — a field left at its default is written as that default, so use redirectSet on a client other things depend on. Returns the client secret once, on create, for a confidential client. Idempotent.

Argument	Type	Required	Description
name	string	yes	Application name; an existing application of this name is converged
appType	enum	yes
authMethod	enum	yes	Client authentication; none is a public PKCE client
accessTokenType	enum	yes
loginVersion	enum	yes	The login UI this client sends a person to; instance sends no choice, so the instance default applies
loginBaseUri?	string	no	With loginVersion v2: the login UI's base URI, when it is not the instance's own

fn ensureApi(name: string, authMethod: enum)

Find or create an API application (a resource server for machine-to-machine calls). Returns the client secret once, on create, for the basic method. Idempotent.

Argument	Type	Required	Description
name	string	yes
authMethod	enum	yes	basic returns a client secret once; jwt authenticates with a key

fn redirectSet()

Add and remove redirect URIs on an OIDC application by reading the live configuration and writing it back with only the allowlist changed — safe on a client others depend on. Idempotent.

fn update(name: string)

Rename an application, leaving its configuration alone. Idempotent.

Argument	Type	Required	Description
name	string	yes	New application name

fn setState(state: enum)

Deactivate or reactivate an application. Reversible, and a no-op when it is already in that state.

Argument	Type	Required	Description
state	enum	yes

fn secretRotate()

Regenerate an application's client secret, verifying the application first. Returns the new secret once; the old one stops working immediately.

fn delete(confirm: string)

Delete an application. Verify-first: confirm must repeat the live name, and dryRun only reports. Prefer setState inactive, which is reversible.

Argument	Type	Required	Description
confirm	string	yes	The application's exact name, repeated — a mismatch refuses the delete

fn keyCreate(expirationDate?: string)

Add a JSON key to an API application for private-key authentication. Returns the key JSON once, marked sensitive.

Argument	Type	Required	Description
expirationDate?	string	no	RFC3339 expiry, e.g. 2027-01-01T00:00:00Z; omit for the instance default

fn keyList()

List an application's keys by id and expiry. Read-only; the key material is not readable after it was created.

fn keyDelete(keyId: string)

Delete an application key, verifying first that it belongs to the application. dryRun only reports.

Argument	Type	Required	Description
keyId	string	yes	Key id, verified to belong to the app

Resources

app(infinite)— An application's configuration; never a secret

app-credential(infinite)— An application's client id, and its client secret once at create or rotate

app-key(infinite)— An application key, with its JSON once at create

oidc-redirect(infinite)— The outcome of changing a redirect allowlist

state(infinite)— The outcome of a reversible state change

deletion(infinite)— The outcome of a delete, or of a dry run that planned one

@dataverket/zitadel/userv2026.10.05.1user.ts

fn list(type: enum)

List users, optionally only the humans or only the machines, and store each one. Read-only.

Argument	Type	Required	Description
type	enum	yes	Narrow the listing to one kind of user

fn get()

Read one user by id or username and store it. Read-only.

fn ensureMachine(username: string, name: string, description?: string, accessTokenType: enum)

Find or create a machine (service) user by username, converging its display name, description and token type. Idempotent, and mints no credential — patCreate, keyCreate or secretGenerate do that.

Argument	Type	Required	Description
username	string	yes	Login name; an existing machine user of this name is converged
name	string	yes	Display name
description?	string	no	Free text; omitting it leaves any existing description as it is, since
accessTokenType	enum	yes

fn ensureHuman(username: string, email: string, givenName: string, familyName: string, displayName?: string, nickName?: string, gender?: enum, preferredLanguage?: string, phone?: string, emailVerified: boolean)

Find or create a human user by username, converging their name and email. Idempotent, and sets no password: the person sets one from a passwordResetLinkCreate link, or from the mail Zitadel sends.

Argument	Type	Required	Description
username	string	yes	Login name; an existing human user of this name is converged
email	string	yes	Email address
givenName	string	yes	First name
familyName	string	yes	Last name
displayName?	string	no
nickName?	string	no
gender?	enum	no
preferredLanguage?	string	no	BCP-47 tag, e.g. nb or en
phone?	string	no	Phone number in E.164 form
emailVerified	boolean	yes	Mark the address verified instead of having Zitadel send a code

fn update(username?: string, email?: string, emailVerified?: boolean, givenName?: string, familyName?: string, displayName?: string, phone?: string, name?: string, description?: string, accessTokenType?: enum)

Change a user's login name, a human's profile or email, or a machine's name, description and token type. Only what is given is sent. Never a password.

Argument	Type	Required	Description
username?	string	no	New login name
email?	string	no	Human users: new email address
emailVerified?	boolean	no
givenName?	string	no
familyName?	string	no
displayName?	string	no
phone?	string	no
name?	string	no	Machine users: new display name
description?	string	no	Machine users: new description
accessTokenType?	enum	no	Machine users: token type

fn setState(state: enum)

Deactivate, reactivate, lock or unlock a user. Every direction is reversible, and asking for the state a user is already in changes nothing.

Argument	Type	Required	Description
state	enum	yes	active reactivates or unlocks, inactive deactivates, locked locks out

fn delete(confirm: string)

Delete a user and everything that belongs to them — grants, tokens, keys. Verify-first: confirm must repeat the live username, and dryRun only reports. Prefer setState inactive, which is reversible.

Argument	Type	Required	Description
confirm	string	yes	The user's exact username, repeated — a mismatch refuses the delete

fn patCreate()

Add a personal access token to a user. Returns the token once, marked sensitive.

fn patList()

List a user's personal access tokens by id and expiry. Read-only; a token's value is not readable after it was created.

fn patRevoke(tokenId: string)

Revoke a personal access token, verifying first that it belongs to the user. dryRun only reports.

Argument	Type	Required	Description
tokenId	string	yes	Token id, verified to belong to the user first

fn keyCreate(publicKey?: string)

Add a private key to a machine user, or register a public key you hold. Returns the generated key JSON once, marked sensitive.

Argument	Type	Required	Description
publicKey?	string	no	A public key to register instead of having Zitadel generate the pair

fn keyList()

List a user's keys by id and expiry. Read-only; key material is not readable after it was created.

fn keyDelete(keyId: string)

Delete a user's key, verifying first that it belongs to them. dryRun only reports.

Argument	Type	Required	Description
keyId	string	yes	Key id, verified to belong to the user first

fn secretGenerate()

Generate a machine user's client secret, replacing any previous one. Returns it once, marked sensitive.

fn secretRemove()

Remove a machine user's client secret, leaving the user in place. dryRun only reports.

fn metadataSet(key: string, value: string)

Set one metadata entry on a user, creating or overwriting it. Idempotent.

Argument	Type	Required	Description
key	string	yes	Metadata key
value	string	yes	Metadata value, stored as given

fn metadataList()

List a user's metadata, decoding each value, and store one resource per entry. Read-only.

fn metadataDelete()

Delete metadata entries from a user by key. dryRun only reports.

fn passwordResetLinkCreate(delivery: enum, urlTemplate?: string)

Mint a password reset for a human user: either a code returned once into a sensitive spec, or a link Zitadel mails to them. No password is ever an argument here.

Argument	Type	Required	Description
delivery	enum	yes	return stores the code once as a secret; email has Zitadel send the link
urlTemplate?	string	no	Link template for the mail, e.g. https://example.org/reset?code={{.Code}}

fn authFactorList()

List what a person can prove who they are with — TOTP, U2F, a code by SMS or email, a passkey — and whether each is ready. Read-only, and the audit behind 'who here actually has MFA'.

fn authFactorRemove(type: enum, id?: string)

Take one authentication factor away from a person — a lost phone, a retired key. Verify-first: the factor has to be there, and u2f and passkey need the id from authFactorList. dryRun only reports. The person can register a new factor afterwards; this does not lock them out by itself, but removing their last factor while MFA is forced will.

Argument	Type	Required	Description
type	enum	yes	Which kind of factor to take away
id?	string	no	The factor's id, needed for u2f and passkey, where a user may have several

fn idpLinkList()

List the identity providers a person can log in through, and their account at each. Read-only.

fn idpLinkRemove(idpId: string, externalUserId: string)

Unlink a person from an identity provider, verifying the link first. dryRun only reports. If that provider was their only way in, they will need a password or a passkey afterwards.

Argument	Type	Required	Description
idpId	string	yes	The identity provider
externalUserId	string	yes	The user's id at that provider, verified against the link first

Resources

user(infinite)— A user, human or machine

user-credential(infinite)— A credential minted for a user — token, key or secret — emitted once

credential(infinite)— A user's existing token or key, by id and expiry; never the secret

metadata(infinite)— One metadata entry on a user

auth-factor(infinite)— One way a person can prove who they are

idp-link(infinite)— A user's account at an identity provider

password-reset(infinite)— A password reset a human can act on

state(infinite)— The outcome of a reversible state change

deletion(infinite)— The outcome of a delete, or of a dry run that planned one

@dataverket/zitadel/grantv2026.10.05.1grant.ts

fn list()

List user grants, optionally narrowed to one user or one project, and store each one under the username and the project's name. Read-only against Zitadel.

fn ensure()

Give a user exactly these roles on a project, creating the grant when it is missing and converging the role set when it is not. Idempotent.

fn setState(state: enum)

Deactivate or reactivate a user grant. Reversible, and a no-op when it is already in that state.

Argument	Type	Required	Description
state	enum	yes

fn delete()

Remove a user's grant on a project, verifying it exists first. dryRun only reports. The grant can be re-created with ensure, so the user keeps their account either way.

Resources

grant(infinite)— A user grant: the roles a user holds on a project

state(infinite)— The outcome of a reversible state change

deletion(infinite)— The outcome of a delete, or of a dry run that planned one

@dataverket/zitadel/actionv2026.10.05.1action.ts

fn list()

List every target and store each one. Read-only, no signing keys.

fn get()

Read one target by id or name and store it. Read-only.

fn ensure(name: string, endpoint: string, style: enum, timeout: string, payloadType?: enum)

Find or create a target by name and converge its endpoint, style and timeout. The signing key comes back once on create, and again when rotateSigningKey asks for a new one. Idempotent.

Argument	Type	Required	Description
name	string	yes	Target name; an existing target of this name is converged
endpoint	string	yes	The URL Zitadel calls, e.g. https://hooks.example.org/zitadel
style	enum	yes	webhook ignores the response, call lets the response change the outcome,
timeout	string	yes	How long Zitadel waits, as a duration with a unit, e.g. 10s
payloadType?	enum	no	How the payload is encoded; jwt and jwe need a public key on the target

fn delete(confirm: string)

Delete a target. Verify-first: confirm must repeat the live name, and dryRun only reports. Executions that named the target stop calling it.

Argument	Type	Required	Description
confirm	string	yes	The target's exact name, repeated — a mismatch refuses the delete

fn executionList()

List every execution with its condition and the targets it calls. Read-only.

fn executionSet()

Bind a condition to an ordered list of targets, replacing whatever that condition called before. Give exactly one condition. Idempotent.

fn executionRemove()

Stop a condition calling anything, by setting it to no targets — which is how Zitadel removes an execution. dryRun only reports.

fn catalog()

Store what an execution condition may name on this instance: the gRPC services, the methods and Zitadel's own functions. Read-only, and the thing to read before writing a condition.

fn keyList()

List a target's public keys by id, state and expiry. Read-only.

fn keyAdd(publicKey: string, expirationDate?: string)

Add a public key to a target, for a payload encrypted to it. Idempotent only in the sense that adding twice adds two keys — list first.

Argument	Type	Required	Description
publicKey	string	yes	PEM public key the payload is encrypted to
expirationDate?	string	no	RFC3339 expiry, if it should have one

fn keySetState(keyId: string, state: enum)

Activate or deactivate a target's public key. Reversible, and the way to retire a key before removing it.

Argument	Type	Required	Description
keyId	string	yes
state	enum	yes

fn keyRemove(keyId: string)

Remove a public key from a target, verifying first that it belongs to it. dryRun only reports.

Argument	Type	Required	Description
keyId	string	yes	Key id, verified to belong to the target

Resources

target(infinite)— An endpoint Zitadel calls, with its delivery style

target-credential(infinite)— A target's signing key, emitted once at create and once at each rotation

public-key(infinite)— A public key a target's payload may be encrypted to

execution(infinite)— A condition bound to the targets it calls, in order

catalog(infinite)— What an execution condition may name on this instance: services, methods, functions

state(infinite)— The outcome of a reversible state change

deletion(infinite)— The outcome of a delete, or of a dry run that planned one

@dataverket/zitadel/settingsv2026.10.05.1settings.ts

fn read(orgId?: string)

Read every settings kind in force for one organization, or for the instance, and store one resource per kind — each saying whether the values are the organization's own or inherited. The instance's OIDC token lifetimes come with either read, as oidc-tokens-instance, when the key may read the instance. Read-only, one run, one lock.

Argument	Type	Required	Description
orgId?	string	no	The organization to read the settings of; omit for the model's own

fn securitySet(iframeEmbeddingEnabled: boolean, enableImpersonation: boolean)

Set the instance's security settings: whether the login UI may be embedded in an iframe, from which origins, and whether impersonation is allowed. Instance-wide — there is no per-organization version of this one.

Argument	Type	Required	Description
iframeEmbeddingEnabled	boolean	yes	Whether the login UI may be embedded in an iframe at all
enableImpersonation	boolean	yes	Whether a holder of an *_IMPERSONATOR role may act as another user

fn loginTranslationSet(locale: string, translations: string, orgId?: string)

Set the hosted login screen's translations for one locale, for an organization or for the instance. The translations are a JSON object of the keys Zitadel's login UI uses.

Argument	Type	Required	Description
locale	string	yes	BCP-47 tag, e.g. nb, en or fr-CH
translations	string	yes	The translations as a JSON object, e.g. {"common":{"back":"Tilbake"}}
orgId?	string	no	The organization to set them for; omit with instance=true for the instance

Resources

oidc-tokens(infinite)— How long access, ID and refresh tokens live, instance-wide; the refresh token lifetimes are the ones a policy decision is about

lockout(infinite)— How many wrong answers lock an account

password-complexity(infinite)— What a password has to look like

password-expiry(infinite)— How long a password lives

branding(infinite)— What the login screen looks like

domain(infinite)— How login names and domains are handled

legal-support(infinite)— The links a login screen shows, and who to ask for help

security(infinite)— Whether the login UI may be framed, and impersonation

general(infinite)— The instance's languages and default organization

identity-provider(infinite)— An identity provider a person may log in with

03Previous Versions5

2026.10.01.3Oct 1, 2026

2026.10.01.2Oct 1, 2026

2026.10.01.1Oct 1, 2026

2026.09.29.2Sep 29, 2026

2026.09.29.1Sep 29, 2026

04Stats

100 / 100

Downloads

Archive size

140.2 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
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/dataverket-org/swamp-extensions

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#zitadel #actions #webhooks #settings #policies #mfa #oidc #iam #auth #identity #users #projects #applications #service-accounts #admin