Skip to main content

zitadel/system.proto

This document reflects the state from API 1.0 (available from 20.04.2021)

SystemService

Healthz

rpc Healthz(HealthzRequest) HealthzResponse

Indicates if ZITADEL is running. It respondes as soon as ZITADEL started

GET: /healthz

ListInstances

rpc ListInstances(ListInstancesRequest) ListInstancesResponse

Returns a list of ZITADEL instances

POST: /instances/_search

GetInstance

rpc GetInstance(GetInstanceRequest) GetInstanceResponse

Returns the detail of an instance

GET: /instances/{instance_id}

AddInstance

rpc AddInstance(AddInstanceRequest) AddInstanceResponse

Creates a new instance with all needed setup data This might take some time

POST: /instances

UpdateInstance

rpc UpdateInstance(UpdateInstanceRequest) UpdateInstanceResponse

Updates name of an existing instance

PUT: /instances/{instance_id}

RemoveInstance

rpc RemoveInstance(RemoveInstanceRequest) RemoveInstanceResponse

Removes a instances This might take some time

DELETE: /instances/{instance_id}

ExistsDomain

rpc ExistsDomain(ExistsDomainRequest) ExistsDomainResponse

Checks if a domain exists

POST: /domains/{domain}/_exists

ListDomains

rpc ListDomains(ListDomainsRequest) ListDomainsResponse

Returns the custom domains of an instance

POST: /instances/{instance_id}/domains/_search

AddDomain

rpc AddDomain(AddDomainRequest) AddDomainResponse

Returns the domain of an instance

POST: /instances/{instance_id}/domains

RemoveDomain

rpc RemoveDomain(RemoveDomainRequest) RemoveDomainResponse

Returns the domain of an instance

DELETE: /instances/{instance_id}/domains/{domain}

SetPrimaryDomain

rpc SetPrimaryDomain(SetPrimaryDomainRequest) SetPrimaryDomainResponse

Returns the domain of an instance

POST: /instances/{instance_id}/domains/_set_primary

ListViews

rpc ListViews(ListViewsRequest) ListViewsResponse

Returns all stored read models of ZITADEL views are used for search optimisation and optimise request latencies they represent the delta of the event happend on the objects

POST: /views/_search

ClearView

rpc ClearView(ClearViewRequest) ClearViewResponse

Truncates the delta of the change stream be carefull with this function because ZITADEL has to recompute the deltas after they got cleared. Search requests will return wrong results until all deltas are recomputed

POST: /views/{database}/{view_name}

ListFailedEvents

rpc ListFailedEvents(ListFailedEventsRequest) ListFailedEventsResponse

Returns event descriptions which cannot be processed. It's possible that some events need some retries. For example if the SMTP-API wasn't able to send an email at the first time

POST: /failedevents/_search

RemoveFailedEvent

rpc RemoveFailedEvent(RemoveFailedEventRequest) RemoveFailedEventResponse

Deletes the event from failed events view. the event is not removed from the change stream This call is usefull if the system was able to process the event later. e.g. if the second try of sending an email was successful. the first try produced a failed event. You can find out if it worked on the failure_count

DELETE: /failedevents/{database}/{view_name}/{failed_sequence}

Messages

AddDomainRequest

FieldTypeDescriptionValidation
instance_idstring-string.min_len: 1
string.max_len: 200
domainstring-string.min_len: 1
string.max_len: 200

AddDomainResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

AddInstanceRequest

FieldTypeDescriptionValidation
instance_namestring-string.min_len: 1
string.max_len: 200
first_org_namestring-string.max_len: 200
custom_domainstring-string.max_len: 200
owner_user_namestring-string.max_len: 200
owner_emailAddInstanceRequest.Email-message.required: true
owner_profileAddInstanceRequest.Profile-message.required: false
owner_passwordAddInstanceRequest.Password-message.required: false
default_languagestring-string.max_len: 10

AddInstanceRequest.Email

FieldTypeDescriptionValidation
emailstring-string.min_len: 1
string.max_len: 200
is_email_verifiedbool-

AddInstanceRequest.Password

FieldTypeDescriptionValidation
passwordstring-string.max_len: 200
password_change_requiredbool-

AddInstanceRequest.Profile

FieldTypeDescriptionValidation
first_namestring-string.max_len: 200
last_namestring-string.max_len: 200
preferred_languagestring-string.max_len: 10

AddInstanceResponse

FieldTypeDescriptionValidation
instance_idstring-
detailszitadel.v1.ObjectDetails-

ChangeSubscriptionRequest

FieldTypeDescriptionValidation
domainstring-string.min_len: 1
string.max_len: 200
subscription_namestring-string.min_len: 1
string.max_len: 200
request_limituint64-
action_mins_limituint64-

ChangeSubscriptionResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

ClearViewRequest

FieldTypeDescriptionValidation
databasestring-string.min_len: 1
string.max_len: 200
view_namestring-string.min_len: 1
string.max_len: 200

ClearViewResponse

This is an empty response

ExistsDomainRequest

FieldTypeDescriptionValidation
domainstring-string.min_len: 1
string.max_len: 200

ExistsDomainResponse

FieldTypeDescriptionValidation
existsbool-

FailedEvent

FieldTypeDescriptionValidation
databasestring-
view_namestring-
failed_sequenceuint64-
failure_countuint64-
error_messagestring-
last_failedgoogle.protobuf.Timestamp-

GetInstanceRequest

FieldTypeDescriptionValidation
instance_idstring-string.min_len: 1
string.max_len: 200

GetInstanceResponse

FieldTypeDescriptionValidation
instancezitadel.instance.v1.InstanceDetail-

GetUsageRequest

FieldTypeDescriptionValidation
instance_idstring-string.min_len: 1
string.max_len: 200

GetUsageResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-
executed_requestsuint64-
executed_action_minsuint64-

HealthzRequest

This is an empty request

HealthzResponse

This is an empty response

ListDomainsRequest

FieldTypeDescriptionValidation
instance_idstringlist limitations and orderingstring.min_len: 1
string.max_len: 200
queryzitadel.v1.ListQuery-
sorting_columnzitadel.instance.v1.DomainFieldNamethe field the result is sorted
queriesrepeated zitadel.instance.v1.DomainSearchQuerycriterias the client is looking for

ListDomainsResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
sorting_columnzitadel.instance.v1.DomainFieldName-
resultrepeated zitadel.instance.v1.Domain-

ListFailedEventsRequest

This is an empty request

ListFailedEventsResponse

FieldTypeDescriptionValidation
resultrepeated FailedEventTODO: list details

ListInstancesRequest

FieldTypeDescriptionValidation
queryzitadel.v1.ListQuerylist limitations and ordering
sorting_columnzitadel.instance.v1.FieldNamethe field the result is sorted
queriesrepeated zitadel.instance.v1.Querycriterias the client is looking for

ListInstancesResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ListDetails-
sorting_columnzitadel.instance.v1.FieldName-
resultrepeated zitadel.instance.v1.Instance-

ListViewsRequest

This is an empty request

ListViewsResponse

FieldTypeDescriptionValidation
resultrepeated ViewTODO: list details

RemoveDomainRequest

FieldTypeDescriptionValidation
instance_idstring-string.min_len: 1
string.max_len: 200
domainstring-string.min_len: 1
string.max_len: 200

RemoveDomainResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

RemoveFailedEventRequest

FieldTypeDescriptionValidation
databasestring-string.min_len: 1
string.max_len: 200
view_namestring-string.min_len: 1
string.max_len: 200
failed_sequenceuint64-
instance_idstring-

RemoveFailedEventResponse

This is an empty response

RemoveInstanceRequest

FieldTypeDescriptionValidation
instance_idstring-string.min_len: 1
string.max_len: 200

RemoveInstanceResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

SetPrimaryDomainRequest

FieldTypeDescriptionValidation
instance_idstring-string.min_len: 1
string.max_len: 200
domainstring-string.min_len: 1
string.max_len: 200

SetPrimaryDomainResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

UpdateInstanceRequest

FieldTypeDescriptionValidation
instance_idstring-
instance_namestring-string.min_len: 1
string.max_len: 200

UpdateInstanceResponse

FieldTypeDescriptionValidation
detailszitadel.v1.ObjectDetails-

View

FieldTypeDescriptionValidation
databasestring-
view_namestring-
processed_sequenceuint64-
event_timestampgoogle.protobuf.TimestampThe timestamp the event occured
last_successful_spooler_rungoogle.protobuf.Timestamp-
instancestring-