Overview

APIs

ZITADEL provides four APIs for different use cases. Three of these APIs are built with GRPC and generate a REST service. Each service's proto definition is located in the source control on GitHub. As we generate the REST services and Swagger file out of the proto definition we recommend that you rely on the proto file. We annotate the corresponding REST methods on each possible call as well as the AuthN and AuthZ requirements. The last API (assets) is only a REST API because ZITADEL uses multipart form data for certain elements.

Proto

All of our APIs are generated by proto defintions. You can find all the proto definitions in the Proto API Definitions.

More about Protocol Buffer

Swagger Documentation

We provide some json files for the swagger documentation of our APIs with the following link: https://api.zitadel.ch/openapi/v2/swagger/ The easiest way to have a look at them is, to import them in the Swagger Editor

Authentication

The authentication API (aka Auth API) is used for all operations on the currently logged in user. The user id is taken from the sub claim in the token.

GRPC

Endpoint: https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/

Definition: Auth Proto

REST

Endpoint: https://api.zitadel.ch/auth/v1/

Swagger Editor: editor.swagger.io

Definition: Swagger Definition

Management

The management API is as the name states the interface where systems can mutate IAM objects like, organizations, projects, clients, users and so on if they have the necessary access rights. To identify the current organization you can send a header x-zitadel-orgid or if no header is set, the organization of the authenticated user is set.

GRPC

Endpoint: https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/

Definition: Management Proto

REST

Endpoint: https://api.zitadel.ch/management/v1/

Swagger Editor: editor.swagger.io

Definition: Swagger Definition

Administration

This API is intended to configure and manage the IAM itself.

GRPC

Endpoint: https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/

Definition: Admin Proto

REST

Endpoint: https://api.zitadel.ch/admin/v1/

Swagger Editor: editor.swagger.io

Definition: Swagger Definition

Assets

The Assets API allows you to up- and download all kinds of assets. This can be files such as logos, fonts or user avatar.

REST

Endpoint: https://api.zitadel.ch/assets/v1/

Definition: Assets

Example

See below for an example with the call GetMyUser.

  //User
  rpc GetMyUser(google.protobuf.Empty) returns (UserView) {
    option (google.api.http) = {
      get: "/users/me"
    };

    option (caos.zitadel.utils.v1.auth_option) = {
      permission: "authenticated"
    };
  }

As you can see the GetMyUser function is also available as a REST service under the path /users/me.

In the table below you can see the URI of those calls.

Service	URI
REST	https://api.zitadel.ch/auth/v1/users/me
GRPC	https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser

Domains

Domain Name	Example	Description
issuer	issuer.zitadel.ch	Provides the OpenID Connect 1.0 Discovery Endpoint
api	api.zitadel.ch	All ZITADEL API's are located under this domain.
login	accounts.zitadel.ch	The accounts.* page provides server renderer pages like login and register and as well the authorization_endpoint for OpenID Connect
console	console.zitadel.ch	With the console.* domain we serve the assets for the management gui