SDK API reference
This reference describes the public preview's Node and Workers entries. All networked methods require a registered environment and independently validated actor/service authority. Their availability does not establish a supported production service.
IdentityServiceClient
connect(configuration, options?) discovers the approved service profile and returns a server-side client. profile() returns credential-free profile metadata.
status(productSubject)returns a validated complete account-status snapshot for an admitted product subject.lifecycle(cursor?, { limit }?)returns a bounded lifecycle page.acknowledge(eventIds, idempotencyKey)submits an explicit acknowledgement command. Persist and reconcile uncertain outcomes with the original key.
These methods do not create user sessions or grant product membership. See configuration and lifecycle.
IdentityProductUserClient
connect(configuration, options?) creates the separate product resource client. The default profile uses connections:write and no client secret.
connectProduct({ accessToken, expectedActor, idempotencyKey }) binds the resource credential to the independently validated subject, broker session, and authentication time before connecting the product. It returns the canonical product connection, not local membership.
The root declarations also retain a local ZITADEL original-pair overload and connectProductWithOriginalSession. These are explicitly development-only; they do not broaden hosted or production support.
IdentityOwnerClient
Node only. connect(configuration, options?) creates the owner client with a subset of the approved owner scopes.
account(authority)reads the owned account projection; it retains the source API's first-use provisioning behavior.sessions(authority, page?)reads a bounded session page.revokeSession(authority, { sessionId, idempotencyKey })requests targeted session revocation.signOutEverywhere(authority, { idempotencyKey })requests the explicit account-wide operation.operation(authority, operationId)reads the owned operation result.
authority contains a call-local access token, the independently validated expected actor, and a synchronous isSessionActive predicate. Recent-auth and scope rules apply. Commands can remain pending and can invalidate the current grant. A request or pending result is not provider-wide completion.
IdentityConsumer
Node only. Construct with { client, store, freshnessMs?, now? }.
registerSubject(subject)establishes the product projection for a verified canonical subject.refreshSubject(subject)requests a current complete snapshot.syncOnce()processes the bounded feed and durable acknowledgements.assertSession({ productSubject, authTime, sessionReference, securityEpoch })validates the session against the current projection at that instant.
The application must still check membership, session lifetime and product permissions, and revalidate authority at the exact business effect.
SQLiteIdentityConsumerStore
Node only. A dedicated product-owned reference store, with transaction, projection/inbox/cursor/acknowledgement operations and close. The source validates private path/ownership and finite capacity requirements. It is not a shared distributed production datastore. See lifecycle.
Protocol helpers and errors
productSessionReference(input): synchronous Node locator; no network or permission grant.productSessionReferenceAsync(input): equivalent asynchronous Workers locator.validateStatus,validateEvent,validateLifecyclePage: strict schema, subject and completeness checks.LIFECYCLE_PROTOCOL:tracecove-lifecycle-v1.IdentitySDKErrorandisIdentityAvailabilityError: fixed-code failures and dependency classification.
Complete declarations
The following declarations are copied from the exact source snapshot used for this preview. Advanced local-provider types are included for source accuracy; they retain their explicit development/loopback limitations. The public archive exports only the Node root and Workers entries.
Node declarations
export interface IdentityProfile {
issuer: string; apiOrigin: string; clientId: string; serviceSubject: string;
tenant: string; environment: string; product: string; audience: string; tokenProfile: 'keycloak-resource-v1';
}
export interface ServiceConfiguration extends IdentityProfile {
clientSecret: string; scopes: string[]; localDevelopment?: boolean;
requestTimeoutMs?: number; maxResponseBytes?: number; maxTokenSeconds?: number;
}
export interface LocalZitadelServiceProfile extends Omit<IdentityProfile, 'tokenProfile'> {
tokenProfile: 'local-zitadel-service-api-v1'; policyFingerprint: string;
}
export interface LocalZitadelServiceConfiguration extends Omit<ServiceConfiguration, 'tokenProfile'> {
tokenProfile: 'local-zitadel-service-api-v1'; localDevelopment: true; environment: 'development';
tokenClientId: string; projectId: string; apiClientId: string; organizationId: string;
accessTokenAudiences: string[]; clientClockSkewSeconds: 0; identityRegistryFingerprint: string;
}
export type ServiceTokenProfile = 'keycloak-resource-v1' | 'local-zitadel-service-api-v1';
export type ServiceClientProfile<P extends ServiceTokenProfile> = P extends 'local-zitadel-service-api-v1' ? LocalZitadelServiceProfile : IdentityProfile;
export interface UserConfiguration extends Omit<IdentityProfile, 'serviceSubject'> {
scopes: string[]; localDevelopment?: boolean; requestTimeoutMs?: number; maxResponseBytes?: number; maxTokenSeconds?: number;
}
export interface LocalZitadelUserConfiguration extends Omit<UserConfiguration, 'tokenProfile'> {
tokenProfile: 'local-zitadel-resource-api-v1'; localDevelopment: true; environment: 'development';
projectId: string; idTokenAudiences: string[]; accessTokenAudiences: string[]; clientClockSkewSeconds: 0;
}
export interface OriginalSessionWitness {
subject: string; brokerSessionId: string; authTime: number; expiresAt: number;
}
export interface OriginalPairConnectionInput {
accessToken: string; idToken: string; expectedActor: OriginalSessionWitness; idempotencyKey: string;
}
export interface OriginalPairConnection {
readonly connection: Readonly<ProductConnection>;
/** Epoch seconds: the earlier verified original ID/access expiry. Not a new session or credential. */
readonly sessionExpiresAt: number;
}
export interface AccountStatus {
product_subject: string; protocol: 'tracecove-lifecycle-v1'; state: 'active' | 'restricted' | 'disabled' | 'deletion_pending' | 'deleted';
security_epoch: number; account_sequence: number; invalid_before: number; revoked_session_refs: string[];
revocations_complete: true; observed_at: string;
}
export interface LifecycleEvent {
event_id: string; product_subject: string; schema_version: 1; protocol: 'tracecove-lifecycle-v1';
type: string; account_sequence: number; security_epoch: number; occurred_at: string; state: AccountStatus['state'];
invalid_before: number; invalidation_kind: 'account' | 'session' | 'status'; snapshot_required: boolean;
revoked_session_ref?: string; method_kind?: string; [key: string]: unknown;
}
export interface LifecyclePage { items: LifecycleEvent[]; next_cursor: string; observed_at: string }
export interface ProductConnection { product_id: string; product_subject: string; account_state: AccountStatus['state']; security_epoch: number; connected_at: string }
export interface ClientOptions { fetch?: typeof fetch; now?: () => number }
declare const userTransportOwnerBrand: unique symbol;
export interface UserClientTransportOwner { readonly profile: 'local-zitadel-user-transport-owner-v1'; readonly [userTransportOwnerBrand]: true }
export interface UserClientTransportStatus {
readonly profile: 'local-zitadel-user-transport-owner-v1'; readonly phase: 'initializing' | 'ready' | 'failed' | 'closing' | 'closed'; readonly activeOperations: number;
readonly transport: null | Readonly<{profile: 'identity-transport-read-custody-v1'; scope: 'tracked-read-promises-only'; activeCalls: number; scheduledOperations: number; ownedCallRecords: number; detachedSchedules: number; detachedLeases: number; unsettled: boolean; retainedLeases: number; pendingOperations: number; quiescent: boolean}>;
}
declare const serviceTransportOwnerBrand: unique symbol;
export interface ServiceClientTransportOwner { readonly profile: 'local-zitadel-service-transport-owner-v1'; readonly [serviceTransportOwnerBrand]: true }
export interface ServiceClientTransportStatus extends Omit<UserClientTransportStatus, 'profile'> { readonly profile: 'local-zitadel-service-transport-owner-v1' }
export class IdentitySDKError extends Error { code: string; status?: number; retryAfterMs?: number; readonly owner?: UserClientTransportOwner | ServiceClientTransportOwner; constructor(code: string, status?: number, retryAfterMs?: number) }
export function isIdentityAvailabilityError(error: unknown): boolean;
export class IdentityServiceClient<P extends ServiceTokenProfile = 'keycloak-resource-v1'> {
private constructor();
static observeLocalTransport(owner: ServiceClientTransportOwner | IdentityServiceClient<'local-zitadel-service-api-v1'>): ServiceClientTransportStatus;
static closeLocalTransport(owner: ServiceClientTransportOwner | IdentityServiceClient<'local-zitadel-service-api-v1'>): void;
static connect(config: ServiceConfiguration, options?: ClientOptions): Promise<IdentityServiceClient>;
static connect(config: LocalZitadelServiceConfiguration, options?: ClientOptions): Promise<IdentityServiceClient<'local-zitadel-service-api-v1'>>;
static connect(config: ServiceConfiguration | LocalZitadelServiceConfiguration, options?: ClientOptions): Promise<IdentityServiceClient<ServiceTokenProfile>>;
profile(): ServiceClientProfile<P>;
status(subject: string): Promise<AccountStatus>;
lifecycle(cursor?: string | null, options?: {limit?: number}): Promise<LifecyclePage>;
acknowledge(eventIds: string[], key: string): Promise<{acknowledged_event_ids: string[]}>;
}
export type UserTokenProfile = 'keycloak-resource-v1' | 'local-zitadel-resource-api-v1';
export class IdentityProductUserClient<P extends UserTokenProfile = 'keycloak-resource-v1'> {
private constructor();
static observeLocalTransport(owner: UserClientTransportOwner | IdentityProductUserClient<'local-zitadel-resource-api-v1'>): UserClientTransportStatus;
static closeLocalTransport(owner: UserClientTransportOwner | IdentityProductUserClient<'local-zitadel-resource-api-v1'>): void;
static connect(config: UserConfiguration, options?: ClientOptions): Promise<IdentityProductUserClient>;
static connect(config: LocalZitadelUserConfiguration, options?: ClientOptions): Promise<IdentityProductUserClient<'local-zitadel-resource-api-v1'>>;
static connect(config: UserConfiguration | LocalZitadelUserConfiguration, options?: ClientOptions): Promise<IdentityProductUserClient<UserTokenProfile>>;
profile(): Omit<IdentityProfile, 'serviceSubject' | 'tokenProfile'> & {tokenProfile: P};
connectProduct(input: P extends 'local-zitadel-resource-api-v1' ?
OriginalPairConnectionInput :
{accessToken: string; expectedActor: {subject: string; brokerSessionId: string; authTime: number}; idempotencyKey: string}): Promise<ProductConnection>;
connectProductWithOriginalSession(input: P extends 'local-zitadel-resource-api-v1' ? OriginalPairConnectionInput : never): Promise<OriginalPairConnection>;
}
export type OwnerScope = 'account:read' | 'sessions:read' | 'sessions:revoke' | 'operations:read';
export interface OwnerProfile extends Omit<IdentityProfile, 'serviceSubject' | 'product' | 'audience'> { audience: 'urn:tracecove:identity-api' }
export interface OwnerConfiguration extends OwnerProfile {
scopes: OwnerScope[]; localDevelopment?: boolean; requestTimeoutMs?: number; maxResponseBytes?: number;
maxTokenSeconds?: number; recentAuthSeconds?: number;
}
export interface OwnerAuthority {
accessToken: string; expectedActor: {subject: string; brokerSessionId: string; authTime: number};
isSessionActive: () => boolean;
}
export interface OwnerAccountView {
account_id: string; state: AccountStatus['state']; security_epoch: number;
products: readonly {product_id: string; display_name: string; connected_at: string}[];
}
export interface OwnerSessionPage {
items: readonly {session_id: string; product_id: string; state: 'active' | 'expired' | 'revoked' | 'revocation_pending'; created_at: string; expires_at: string}[];
next_cursor: string | null; observed_at: string;
}
export interface OwnerSessionOperation {
operation_id: string; kind: 'revoke_session' | 'sign_out_everywhere'; state: 'pending' | 'completed' | 'failed';
created_at: string; failure_code?: string;
}
export class IdentityOwnerClient {
private constructor();
static connect(config: OwnerConfiguration, options?: ClientOptions): Promise<IdentityOwnerClient>;
profile(): OwnerProfile;
account(authority: OwnerAuthority): Promise<OwnerAccountView>;
sessions(authority: OwnerAuthority, page?: {cursor?: string | null; limit?: number}): Promise<OwnerSessionPage>;
revokeSession(authority: OwnerAuthority, command: {sessionId: string; idempotencyKey: string}): Promise<OwnerSessionOperation>;
signOutEverywhere(authority: OwnerAuthority, command: {idempotencyKey: string}): Promise<OwnerSessionOperation>;
operation(authority: OwnerAuthority, operationId: string): Promise<OwnerSessionOperation>;
}
export function validateOwnerConfiguration(input: OwnerConfiguration): OwnerConfiguration;
export interface ConsumerProjection { snapshot: AccountStatus | null; checkedAt: number | null; valid: boolean }
export interface ConsumerStore<P extends ServiceTokenProfile = 'keycloak-resource-v1'> {
profile(): ServiceClientProfile<P>; transaction<T>(callback: (tx: ConsumerStore<P>) => T | Promise<T>): Promise<T>;
subjects(): string[] | Promise<string[]>; registerSubject(subject: string): void | Promise<void>;
projection(subject: string): ConsumerProjection | null | Promise<ConsumerProjection | null>;
commitSnapshot(snapshot: AccountStatus, checkedAt: number): void | Promise<void>; recordEvent(event: LifecycleEvent): void | Promise<void>;
cursor(): string | null | Promise<string | null>; setCursor(cursor: string | null): void | Promise<void>;
enqueueAcknowledgement(command: {key: string; eventIds: string[]}): void | Promise<void>;
pendingAcknowledgements(): {key: string; eventIds: string[]; blocked?: boolean}[] | Promise<{key: string; eventIds: string[]; blocked?: boolean}[]>;
removeAcknowledgement(key: string): void | Promise<void>; markAcknowledgementBlocked(key: string): void | Promise<void>; invalidateAll(): void | Promise<void>;
}
export class IdentityConsumer<P extends ServiceTokenProfile = 'keycloak-resource-v1'> {
constructor(input: {client: IdentityServiceClient<P>; store: ConsumerStore<P>; now?: () => number; freshnessMs?: number});
registerSubject(subject: string): Promise<{state: AccountStatus['state']; securityEpoch: number}>;
refreshSubject(subject: string): Promise<{state: AccountStatus['state']; securityEpoch: number}>;
syncOnce(): Promise<{appliedEvents: number; refreshedSubjects: number; resynchronized: boolean; acknowledgementPending: boolean; acknowledgementBlocked: boolean}>;
assertSession(input: {productSubject: string; authTime: number; sessionReference: string; securityEpoch: number}): Promise<{state: 'active'; sessionSecurityEpoch: number; observedSecurityEpoch: number}>;
}
export class SQLiteIdentityConsumerStore<P extends ServiceTokenProfile = 'keycloak-resource-v1'> implements ConsumerStore<P> {
constructor(path: string, options: {profile: Omit<IdentityProfile, 'tokenProfile'> & {tokenProfile: P} & (P extends 'local-zitadel-service-api-v1' ? {policyFingerprint: string} : unknown); maxSubjects?: number; maxInboxEvents?: number; maxPendingAcknowledgements?: number});
profile(): ServiceClientProfile<P>; transaction<T>(callback: (tx: ConsumerStore<P>) => T | Promise<T>): Promise<T>;
subjects(): string[]; registerSubject(subject: string): void; projection(subject: string): ConsumerProjection | null;
commitSnapshot(snapshot: AccountStatus, checkedAt: number): void; recordEvent(event: LifecycleEvent): void;
cursor(): string | null; setCursor(cursor: string | null): void;
enqueueAcknowledgement(command: {key: string; eventIds: string[]}): void;
pendingAcknowledgements(): {key: string; eventIds: string[]; blocked?: boolean}[]; removeAcknowledgement(key: string): void; markAcknowledgementBlocked(key: string): void; invalidateAll(): void; close(): void;
}
export function validateServiceConfiguration(input: ServiceConfiguration): ServiceConfiguration;
export function validateServiceConfiguration(input: LocalZitadelServiceConfiguration): LocalZitadelServiceConfiguration;
export function validateUserConfiguration(input: UserConfiguration): UserConfiguration;
export function validateUserConfiguration(input: LocalZitadelUserConfiguration): LocalZitadelUserConfiguration;
export function productSessionReference(input: {tenant: string; environment: string; issuer: string; product: string; productSubject: string; brokerSessionId: string}): string;
export function validateStatus(input: unknown, expectedSubject: string): AccountStatus;
export function validateEvent(input: unknown): LifecycleEvent;
export function validateLifecyclePage(input: unknown): LifecyclePage;
export const LIFECYCLE_PROTOCOL: 'tracecove-lifecycle-v1';
Workers declarations
export {
IdentitySDKError, isIdentityAvailabilityError, IdentityServiceClient, validateServiceConfiguration,
IdentityProductUserClient, validateUserConfiguration, LIFECYCLE_PROTOCOL,
validateStatus, validateEvent, validateLifecyclePage,
} from './index.js';
export type {
IdentityProfile, ServiceConfiguration, UserConfiguration, LocalZitadelUserConfiguration, OriginalSessionWitness, UserTokenProfile, AccountStatus, LifecycleEvent,
LifecyclePage, ProductConnection, ClientOptions, UserClientTransportOwner, UserClientTransportStatus,
LocalZitadelServiceProfile, LocalZitadelServiceConfiguration, ServiceTokenProfile, ServiceClientProfile, ServiceClientTransportOwner, ServiceClientTransportStatus,
} from './index.js';
export function productSessionReferenceAsync(input: {
tenant: string; environment: string; issuer: string; product: string; productSubject: string; brokerSessionId: string;
}): Promise<string>;
Public preview 0.7.0-preview.1 · Not production ready · Status and releases