ZITADEL API Reference Overview

ZITADEL exposes all features via different gRPC and REST APIs and provides SDKs for popular languages and frameworks.

The OpenID Connect & OAuth endpoints and SAML 2.0 endpoints are implemented and exposed according to the specific standards. Managing resources such as users, organizations, instances, or settings must be done with the different ZITADEL APIs.

Actions allow to extend ZITADEL with custom code to change default behaviors or calling external systems.

Authentication & authorization

Authentication for human users (interactive)

ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication. Please refer to our guides how to authenticate users through an interactive authentication process.

For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the device authorization grant.

Additionally, you can use the session API to authenticate users, for example by building a custom login UI.

Authenticate service users and machines

Service users allow for machine-to-machine (M2M) communication. Follow the guides to learn how to authenticate service users.

Accessing the ZITADEL APIs through a service user might require additional steps, please follow the guide on how to access ZITADEL APIs to include the correct audience scope in your requests.

OpenID Connect & OAuth

• OpenID Connect endpoints definition
• Standard and reserved scopes reference
• Standard, custom, and reserved claims reference

The OIDC Playground is for testing OpenID authentication requests and their parameters.

SAML 2.0

• SAML 2.0 endpoints definition
• Custom attributes can be added with an action

Custom

ZITADEL allows to authenticate users by creating a session with the Session API or get OIDC authentication request details with the OIDC service API. User authorizations can be retrieved as roles from our APIs.

Refer to our guide to learn how to build your own login UI

ZITADEL APIs (resource-based)

ZITADEL provides APIs for each core resource:

• User
• Session
• Settings

info

We are migrating to a resource-based API approach. You might need to use the existing service-based APIs for now to manage Organizations, Instances, Assets etc.

ZITADEL APIs (service-based)

Prefer resource-based API

ZITADEL APIs were organized by UseCase/Context, such as Auth API for authenticated users and Management API for organization managers. This led to confusion about which API to use, particularly for requests that could be useful across multiple APIs but with different filters. For instance, SearchUsers on an Instance Level or on an Organization Level.

To address this issue, ZITADEL is migrating to a resource-based API.

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: $ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/

Definition: Auth Proto

REST

Endpoint: $ZITADEL_DOMAIN/auth/v1/

API Reference: OpenAPI Docs

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: $ZITADEL_DOMAIN/zitadel.management.v1.ManagementService/

Definition: Management Proto

REST

Endpoint: $ZITADEL_DOMAIN/management/v1/

API Reference: OpenAPI Docs

Administration

This API is intended to configure and manage one ZITADEL instance itself.

GRPC

Endpoint: $ZITADEL_DOMAIN/zitadel.admin.v1.AdminService/

Definition: Admin Proto

REST

Endpoint: $ZITADEL_DOMAIN/admin/v1/

API Reference: OpenAPI Docs

System

This API is intended to manage the different ZITADEL instances within the system.

Checkout the guide how to access the ZITADEL System API.

GRPC

Endpoint: $ZITADEL_DOMAIN/zitadel.system.v1.SystemService/

Definition: System Proto

REST

Endpoint: $ZITADEL_DOMAIN/system/v1/

API Reference: OpenAPI Docs

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: $ZITADEL_DOMAIN/assets/v1/

Definition: Assets

API definitions

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.

SDKs

ZITADEL provides some official and community supported SDKs for multiple languages and frameworks. Most languages allow you to build a client from proto definitions, which allows you to build your own client in case an SDK is missing.

Proto

All of our APIs are generated by proto definitions. 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://zitadel.cloud/openapi/v2/swagger/

The easiest way to have a look at them is, to import them in the Swagger Editor

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 (zitadel.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	$ZITADEL_DOMAIN/auth/v1/users/me
GRPC	$ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/GetMyUser

Domains

ZITADEL hosts everything under a single domain: {instance}.zitadel.cloud or your custom domain $ZITADEL_DOMAIN

The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Console UI, which you'll find under {your_domain}/ui/console/.

Are you self-hosting and having troubles with Instance not found errors? Check out this page.

API path prefixes

If you run ZITADEL on a custom domain, you may want to reuse that domain for other applications. For easy copying to your reverse proxy configuration, here is the list of URL path prefixes, ZITADEL uses.

/zitadel.admin.v1.AdminService/
/admin/v1/
/zitadel.auth.v1.AuthService/
/auth/v1/
/zitadel.management.v1.ManagementService/
/management/v1/
/zitadel.system.v1.SystemService/
/system/v1/
/assets/v1/
/ui/
/oidc/v1/
/saml/v2/
/oauth/v2/
/device
/.well-known/openid-configuration
/openapi/
/idps/callback
/v2beta/
/zitadel.user.v2beta.UserService/
/zitadel.session.v2beta.SessionService/
/zitadel.settings.v2beta.SettingsService/
/zitadel.oidc.v2beta.OIDCService/
/zitadel.org.v2beta.OrganizationService/
/v2/
/zitadel.user.v2.UserService/
/zitadel.session.v2.SessionService/
/zitadel.settings.v2.SettingsService/
/zitadel.oidc.v2.OIDCService/
/zitadel.org.v2.OrganizationService/