Configuration
Configuration comes from a trusted, registered environment. Pin it on the server. A browser or request body must not choose the issuer, API, product, audience, client, tenant, or environment.
Service profile
The default service client uses the named keycloak-resource-v1 profile. The values below are placeholders, not a running environment. Supply your own operator-issued values; the documentation website is not an issuer or API.
const serviceConfiguration = {
issuer: process.env.IDENTITY_ISSUER,
apiOrigin: process.env.IDENTITY_API_ORIGIN,
clientId: process.env.IDENTITY_CLIENT_ID,
clientSecret: process.env.IDENTITY_CLIENT_SECRET,
serviceSubject: process.env.IDENTITY_SERVICE_SUBJECT,
tenant: process.env.IDENTITY_TENANT,
environment: 'staging',
product: 'example-app',
audience: 'urn:tracecove:identity-api',
tokenProfile: 'keycloak-resource-v1',
scopes: ['status:read', 'lifecycle:read', 'lifecycle:ack'],
};issuer: the exact approved issuer URL. Discovery, token, and JWKS origins are constrained by the profile.apiOrigin: the approved Identity resource API origin, without a path, query, credentials, or fragment.clientId,clientSecret,serviceSubject: the separately registered machine client and its actual provider subject.tenant,environment,product: the exact registered namespace. A product connection never supplies business membership by itself.audience: exactlyurn:tracecove:identity-apifor this profile.scopes: the three required service scopes.evidence:readis optional only when separately granted. Unknown, duplicate, or missing scopes fail closed.
Transport and bounds
HTTPS is required by default. The Node client's normal request timeout is 5,000 ms, bounded to 100–10,000 ms. Response size defaults to a maximum of 131,072 bytes; maximum token lifetime defaults to 300 seconds and can only be reduced within the accepted range.
HTTP is permitted only for literal numeric loopback issuer and API origins when localDevelopment: true and environment: 'development'. This exception does not permit a remote plaintext issuer. An application running locally against hosted staging still uses HTTPS for its broker/API; its own callback transport is a separate concern.
The per-client transport has a finite queue, deadlines, cooldown, and ownership of unsettled work. Reuse an owned Node client rather than creating one for every request. These bounds are not a distributed rate limit or a production availability guarantee. Workers has a different request ownership rule.
Separate client roles
The product-user client uses a public resource client with connections:write and no client secret. The owner client uses its own approved owner scopes and verified owner authority. Neither is a machine service principal. See concepts and the API reference.
Local provider overloads
The included root declarations retain development-only ZITADEL overloads from the source SDK. Their loopback, audience, actor, lifetime, and policy checks still apply. They are not a general hosted-provider adapter or production feature. The private local-zitadel-login and synthetic-deletion entry points are not exported by this public package.
Public preview 0.7.0-preview.1 · Not production ready · Status and releases