Zitadel
Zitadel for swamp, over its API: nine 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, a password reset that mints a link rather than taking a password, and a passkey registration link that lets a person register a passkey on the host the link names without logging in first. @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, with the instance's token lifetimes, secret generators, email providers and notification settings beside them, writes the two that v2 exposes, and sets how long a one-time code such as a passkey registration code stays valid. @dataverket/zitadel/system is the instances a deployment hosts, kept with a System API user: each instance's domain list — list, add, remove verify-first, set the primary — and the instances themselves, listed and created with a first organization and a machine owner whose token or key is emitted once. @dataverket/zitadel/instance is the same instance read with an ordinary key: its domains, the domains it trusts, and every holder of an instance role; trusted domains are added and removed verify-first.
Projects also carry their grants to other organizations, and the members who administer them; users carry their authentication factors and identity-provider links, and one run can audit every human's factors with a summary per person, which is what "who here actually has 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. Or a bearer token in a file (accessTokenFile), sent as it is, so a workflow runs as the person whose login wrote it. The system type signs with a System API user's key (systemKeyFile, systemUser), which is the bearer itself. 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.
Resources
| Argument | Type | Description |
|---|---|---|
| name | string | Project name; an existing project of this name is reused |
| roleAssertion? | boolean | Assert the user's roles into tokens and the userinfo endpoint |
| roleCheck? | boolean | Require a role of this project for a user to log in |
| hasProjectCheck? | boolean | Require the user's organization to be granted this project |
| Argument | Type | Description |
|---|---|---|
| name? | string | New project name |
| roleAssertion? | boolean | |
| roleCheck? | boolean | |
| hasProjectCheck? | boolean |
| Argument | Type | Description |
|---|---|---|
| state | enum | Target state; the change is reversible either way |
| Argument | Type | Description |
|---|---|---|
| confirm | string | The project's exact name, repeated — a mismatch refuses the delete |
| Argument | Type | Description |
|---|---|---|
| displayName? | string | Human-readable role name |
| group? | string | Group the role belongs to |
| Argument | Type | Description |
|---|---|---|
| state | enum |
| Argument | Type | Description |
|---|---|---|
| confirm | string | The granted organization's exact name, or its id when it has no name — |
| Argument | Type | Description |
|---|---|---|
| userId | string | A user of the granted organization |
| Argument | Type | Description |
|---|---|---|
| userId | string |
Resources
| Argument | Type | Description |
|---|---|---|
| name | string | Application name; an existing application of this name is converged |
| appType? | enum | |
| authMethod? | enum | Client authentication; none is a public PKCE client |
| accessTokenType? | enum | |
| loginVersion? | enum | The login UI this client sends a person to; instance sends no choice, so the instance default applies |
| loginBaseUri? | string | With loginVersion v2: the login UI's base URI, when it is not the instance's own |
| Argument | Type | Description |
|---|---|---|
| name | string | |
| authMethod? | enum | basic returns a client secret once; jwt authenticates with a key |
| Argument | Type | Description |
|---|---|---|
| name | string | New application name |
| Argument | Type | Description |
|---|---|---|
| state | enum |
| Argument | Type | Description |
|---|---|---|
| confirm | string | The application's exact name, repeated — a mismatch refuses the delete |
| Argument | Type | Description |
|---|---|---|
| expirationDate? | string | RFC3339 expiry, e.g. 2027-01-01T00:00:00Z; omit for the instance default |
| Argument | Type | Description |
|---|---|---|
| keyId | string | Key id, verified to belong to the app |
Resources
| Argument | Type | Description |
|---|---|---|
| type? | enum | Narrow the listing to one kind of user |
| Argument | Type | Description |
|---|---|---|
| username | string | Login name; an existing machine user of this name is converged |
| name | string | Display name |
| description? | string | Free text; omitting it leaves any existing description as it is, since |
| accessTokenType? | enum |
| Argument | Type | Description |
|---|---|---|
| username | string | Login name; an existing human user of this name is converged |
| string | Email address | |
| givenName | string | First name |
| familyName | string | Last name |
| displayName? | string | |
| nickName? | string | |
| gender? | enum | |
| preferredLanguage? | string | BCP-47 tag, e.g. nb or en |
| phone? | string | Phone number in E.164 form |
| emailVerified? | boolean | Mark the address verified instead of having Zitadel send a code |
| Argument | Type | Description |
|---|---|---|
| username? | string | New login name |
| email? | string | Human users: new email address |
| emailVerified? | boolean | |
| givenName? | string | |
| familyName? | string | |
| displayName? | string | |
| phone? | string | |
| name? | string | Machine users: new display name |
| description? | string | Machine users: new description |
| accessTokenType? | enum | Machine users: token type |
| Argument | Type | Description |
|---|---|---|
| state | enum | active reactivates or unlocks, inactive deactivates, locked locks out |
| Argument | Type | Description |
|---|---|---|
| confirm | string | The user's exact username, repeated — a mismatch refuses the delete |
| Argument | Type | Description |
|---|---|---|
| tokenId | string | Token id, verified to belong to the user first |
| Argument | Type | Description |
|---|---|---|
| publicKey? | string | A public key to register instead of having Zitadel generate the pair |
| Argument | Type | Description |
|---|---|---|
| keyId | string | Key id, verified to belong to the user first |
| Argument | Type | Description |
|---|---|---|
| key | string | Metadata key |
| value | string | Metadata value, stored as given |
| Argument | Type | Description |
|---|---|---|
| delivery? | enum | return stores the code once as a secret; email has Zitadel send the link |
| urlTemplate? | string | Link template for the mail, e.g. https://example.org/reset?code={{.Code}} |
| Argument | Type | Description |
|---|---|---|
| delivery? | enum | return stores the code and its id once as a secret; email has Zitadel |
| urlTemplate? | string | Link template for the mail; the passkey binds to the host the page is |
| Argument | Type | Description |
|---|---|---|
| user? | string | One person, by user id or username; omit to audit every human in the |
| Argument | Type | Description |
|---|---|---|
| type | enum | Which kind of factor to take away |
| id? | string | The factor's id, needed for u2f and passkey, where a user may have several |
| Argument | Type | Description |
|---|---|---|
| idpId | string | The identity provider |
| externalUserId | string | The user's id at that provider, verified against the link first |
Resources
| Argument | Type | Description |
|---|---|---|
| state | enum |
Resources
| Argument | Type | Description |
|---|---|---|
| name | string | Target name; an existing target of this name is converged |
| endpoint | string | The URL Zitadel calls, e.g. https://hooks.example.org/zitadel |
| style? | enum | webhook ignores the response, call lets the response change the outcome, |
| timeout? | string | How long Zitadel waits, as a duration with a unit, e.g. 10s |
| payloadType? | enum | How the payload is encoded; jwt and jwe need a public key on the target |
| Argument | Type | Description |
|---|---|---|
| confirm | string | The target's exact name, repeated — a mismatch refuses the delete |
| Argument | Type | Description |
|---|---|---|
| publicKey | string | PEM public key the payload is encrypted to |
| expirationDate? | string | RFC3339 expiry, if it should have one |
| Argument | Type | Description |
|---|---|---|
| keyId | string | |
| state | enum |
| Argument | Type | Description |
|---|---|---|
| keyId | string | Key id, verified to belong to the target |
Resources
| Argument | Type | Description |
|---|---|---|
| orgId? | string | The organization to read the settings of; omit for the model's own |
| Argument | Type | Description |
|---|---|---|
| iframeEmbeddingEnabled | boolean | Whether the login UI may be embedded in an iframe at all |
| enableImpersonation | boolean | Whether a holder of an *_IMPERSONATOR role may act as another user |
| Argument | Type | Description |
|---|---|---|
| generator | enum | Which kind of code: passwordlessInitCode is the passkey registration code, initCode the first-login code, passwordResetCode, verifyEmailCode, verifyPhoneCode, otpEmail and otpSms the others, appSecret a client secret |
| expirySeconds? | coerce.number | How long a code stays valid, in seconds; e.g. 172800 for two days. Omit to keep the current value |
| length? | coerce.number | How many characters a code has; omit to keep the current value |
| Argument | Type | Description |
|---|---|---|
| locale | string | BCP-47 tag, e.g. nb, en or fr-CH |
| translations | string | The translations as a JSON object, e.g. {"common":{"back":"Tilbake"}} |
| orgId? | string | The organization to set them for; omit with instance=true for the instance |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Zitadel base URL and issuer, e.g. https://zitadel.example.org; the |
| systemUser | string | The key's name in the instance's SystemAPIUsers configuration; the |
| systemKeyFile | string | Path to the System API user's RSA private key, PEM, read at call time; |
| instanceId? | string | The instance to act on. Omit when the System API lists exactly one, |
| httpTimeoutMs? | coerce.number | Per-request timeout in milliseconds |
| Argument | Type | Description |
|---|---|---|
| name | string | The instance's name; an instance already named so is left as it is |
| firstOrgName? | string | The first organization's name; Zitadel names it ZITADEL when omitted |
| customDomain? | string | A custom domain added at creation, e.g. id.example.org, beside the |
| defaultLanguage? | string | BCP-47 tag for the instance's default language, e.g. nb or en |
| ownerUsername? | string | The machine user made in the first organization as the instance's |
| ownerName? | string | The owner's display name; the username when omitted |
| ownerCredential? | enum | What is minted for the owner, once: pat is a personal access token that |
| expirationDate | string | RFC3339 expiry of the owner's token or key, e.g. 2027-01-01T00:00:00Z; |
| Argument | Type | Description |
|---|---|---|
| domain | string | The domain, e.g. id.example.org |
| Argument | Type | Description |
|---|---|---|
| domain | string | The domain to remove |
| confirm | string | Must repeat the domain exactly; the method refuses otherwise |
| Argument | Type | Description |
|---|---|---|
| domain | string | The domain, e.g. id.example.org |
Resources
| Argument | Type | Description |
|---|---|---|
| domain | string | The host, e.g. login.example.org |
| Argument | Type | Description |
|---|---|---|
| domain | string | The trusted domain to remove |
| confirm | string | Must repeat the domain exactly; the method refuses otherwise |
Resources
Added 1, modified 3 behaviors. updated labels
Modified 1 behaviors
Added 1, modified 1 behaviors
Modified 1 behaviors
- 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
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
A field that looks like a secret but is not marked sensitive, so its value is not vaulted.
- models/common.ts:34 — no reason given
- models/common.ts:49 — no reason given
- models/schema.ts:834 — no reason given
- models/schema.ts:839 — no reason given
- models/schema.ts:842 — no reason given
- models/schema.ts:847 — no reason given
- models/schema.ts:909 — no reason given