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

Deprecated: Use CreateInstance instead 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}

CreateInstance

rpc CreateInstance(CreateInstanceRequest) CreateInstanceResponse

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

POST: /instances/_create

RemoveInstance

rpc RemoveInstance(RemoveInstanceRequest) RemoveInstanceResponse

Removes a instances This might take some time

DELETE: /instances/{instance_id}

ListIAMMembers

rpc ListIAMMembers(ListIAMMembersRequest) ListIAMMembersResponse

Returns all instance members matching the request all queries need to match (ANDed)

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

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

Field	Type	Description	Validation
instance_id	string	-	string.min_len: 1 string.max_len: 200
domain	string	-	string.min_len: 1 string.max_len: 200

AddDomainResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-

AddInstanceRequest

Field	Type	Description	Validation
instance_name	string	-	string.min_len: 1 string.max_len: 200
first_org_name	string	-	string.max_len: 200
custom_domain	string	-	string.max_len: 200
owner_user_name	string	-	string.max_len: 200
owner_email	AddInstanceRequest.Email	-	message.required: true
owner_profile	AddInstanceRequest.Profile	-	message.required: false
owner_password	AddInstanceRequest.Password	-	message.required: false
default_language	string	-	string.max_len: 10

AddInstanceRequest.Email

Field	Type	Description	Validation
email	string	-	string.min_len: 1 string.max_len: 200
is_email_verified	bool	-

AddInstanceRequest.Password

Field	Type	Description	Validation
password	string	-	string.max_len: 200
password_change_required	bool	-

AddInstanceRequest.Profile

Field	Type	Description	Validation
first_name	string	-	string.max_len: 200
last_name	string	-	string.max_len: 200
preferred_language	string	-	string.max_len: 10

AddInstanceResponse

Field	Type	Description	Validation
instance_id	string	-
details	zitadel.v1.ObjectDetails	-

ChangeSubscriptionRequest

Field	Type	Description	Validation
domain	string	-	string.min_len: 1 string.max_len: 200
subscription_name	string	-	string.min_len: 1 string.max_len: 200
request_limit	uint64	-
action_mins_limit	uint64	-

ChangeSubscriptionResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-

ClearViewRequest

Field	Type	Description	Validation
database	string	-	string.min_len: 1 string.max_len: 200
view_name	string	-	string.min_len: 1 string.max_len: 200

ClearViewResponse

This is an empty response

CreateInstanceRequest

Field	Type	Description	Validation
instance_name	string	-	string.min_len: 1 string.max_len: 200
first_org_name	string	-	string.max_len: 200
custom_domain	string	-	string.max_len: 200
oneof owner.human	CreateInstanceRequest.Human	oneof field for the user managing the instance
oneof owner.machine	CreateInstanceRequest.Machine	-
default_language	string	-	string.max_len: 10

CreateInstanceRequest.Email

Field	Type	Description	Validation
email	string	-	string.min_len: 1 string.max_len: 200 string.email: true
is_email_verified	bool	-

CreateInstanceRequest.Human

Field	Type	Description	Validation
user_name	string	-	string.max_len: 200
email	CreateInstanceRequest.Email	-	message.required: true
profile	CreateInstanceRequest.Profile	-	message.required: false
password	CreateInstanceRequest.Password	-	message.required: false

CreateInstanceRequest.Machine

Field	Type	Description	Validation
user_name	string	-	string.max_len: 200
name	string	-	string.max_len: 200
personal_access_token	CreateInstanceRequest.PersonalAccessToken	-
machine_key	CreateInstanceRequest.MachineKey	-

CreateInstanceRequest.MachineKey

Field	Type	Description	Validation
type	zitadel.authn.v1.KeyType	-	enum.defined_only: true enum.not_in: [0]
expiration_date	google.protobuf.Timestamp	-

CreateInstanceRequest.Password

Field	Type	Description	Validation
password	string	-	string.max_len: 200
password_change_required	bool	-

CreateInstanceRequest.PersonalAccessToken

Field	Type	Description	Validation
expiration_date	google.protobuf.Timestamp	-

CreateInstanceRequest.Profile

Field	Type	Description	Validation
first_name	string	-	string.max_len: 200
last_name	string	-	string.max_len: 200
preferred_language	string	-	string.max_len: 10

CreateInstanceResponse

Field	Type	Description	Validation
instance_id	string	-
details	zitadel.v1.ObjectDetails	-
pat	string	-
machine_key	bytes	-

ExistsDomainRequest

Field	Type	Description	Validation
domain	string	-	string.min_len: 1 string.max_len: 200

ExistsDomainResponse

Field	Type	Description	Validation
exists	bool	-

FailedEvent

Field	Type	Description	Validation
database	string	-
view_name	string	-
failed_sequence	uint64	-
failure_count	uint64	-
error_message	string	-
last_failed	google.protobuf.Timestamp	-

GetInstanceRequest

Field	Type	Description	Validation
instance_id	string	-	string.min_len: 1 string.max_len: 200

GetInstanceResponse

Field	Type	Description	Validation
instance	zitadel.instance.v1.InstanceDetail	-

GetUsageRequest

Field	Type	Description	Validation
instance_id	string	-	string.min_len: 1 string.max_len: 200

GetUsageResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-
executed_requests	uint64	-
executed_action_mins	uint64	-

HealthzRequest

This is an empty request

HealthzResponse

This is an empty response

ListDomainsRequest

Field	Type	Description	Validation
instance_id	string	list limitations and ordering	string.min_len: 1 string.max_len: 200
query	zitadel.v1.ListQuery	-
sorting_column	zitadel.instance.v1.DomainFieldName	the field the result is sorted
queries	repeated zitadel.instance.v1.DomainSearchQuery	criterias the client is looking for

ListDomainsResponse

Field	Type	Description	Validation
details	zitadel.v1.ListDetails	-
sorting_column	zitadel.instance.v1.DomainFieldName	-
result	repeated zitadel.instance.v1.Domain	-

ListFailedEventsRequest

This is an empty request

ListFailedEventsResponse

Field	Type	Description	Validation
result	repeated FailedEvent	TODO: list details

ListIAMMembersRequest

Field	Type	Description	Validation
query	zitadel.v1.ListQuery	-
instance_id	string	-
queries	repeated zitadel.member.v1.SearchQuery	-

ListIAMMembersResponse

Field	Type	Description	Validation
details	zitadel.v1.ListDetails	-
result	repeated zitadel.member.v1.Member	-

ListInstancesRequest

Field	Type	Description	Validation
query	zitadel.v1.ListQuery	list limitations and ordering
sorting_column	zitadel.instance.v1.FieldName	the field the result is sorted
queries	repeated zitadel.instance.v1.Query	criterias the client is looking for

ListInstancesResponse

Field	Type	Description	Validation
details	zitadel.v1.ListDetails	-
sorting_column	zitadel.instance.v1.FieldName	-
result	repeated zitadel.instance.v1.Instance	-

ListViewsRequest

This is an empty request

ListViewsResponse

Field	Type	Description	Validation
result	repeated View	TODO: list details

RemoveDomainRequest

Field	Type	Description	Validation
instance_id	string	-	string.min_len: 1 string.max_len: 200
domain	string	-	string.min_len: 1 string.max_len: 200

RemoveDomainResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-

RemoveFailedEventRequest

Field	Type	Description	Validation
database	string	-	string.min_len: 1 string.max_len: 200
view_name	string	-	string.min_len: 1 string.max_len: 200
failed_sequence	uint64	-
instance_id	string	-

RemoveFailedEventResponse

This is an empty response

RemoveInstanceRequest

Field	Type	Description	Validation
instance_id	string	-	string.min_len: 1 string.max_len: 200

RemoveInstanceResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-

SetPrimaryDomainRequest

Field	Type	Description	Validation
instance_id	string	-	string.min_len: 1 string.max_len: 200
domain	string	-	string.min_len: 1 string.max_len: 200

SetPrimaryDomainResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-

UpdateInstanceRequest

Field	Type	Description	Validation
instance_id	string	-
instance_name	string	-	string.min_len: 1 string.max_len: 200

UpdateInstanceResponse

Field	Type	Description	Validation
details	zitadel.v1.ObjectDetails	-

View

Field	Type	Description	Validation
database	string	-
view_name	string	-
processed_sequence	uint64	-
event_timestamp	google.protobuf.Timestamp	The timestamp the event occured
last_successful_spooler_run	google.protobuf.Timestamp	-
instance	string	-