---
title: ZITADEL API Reference Overview
sidebar_label: Overview
---

import { ApiCard } from "@/components/apicard";
import Column from "@/components/column";

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

The [OpenID Connect & OAuth endpoints](/apis/openidoauth/endpoints) and [SAML 2.0 endpoints](/apis/saml/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](#zitadel-apis-resource-based).

[Actions](/guides/manage/console/actions-overview) 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](/guides/integrate/login/login-users) through an interactive authentication process.

For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the [device authorization grant](/guides/integrate/login/oidc/device-authorization).

Additionally, you can use the [session API](/reference/api/session) to authenticate users, for example by building a [custom login UI](/guides/integrate/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](/guides/integrate/service-users/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](../guides/integrate/zitadel-apis/access-zitadel-apis) to include the correct audience scope in your requests.

### OpenID Connect & OAuth

- [OpenID Connect endpoints](/apis/openidoauth/endpoints) definition
- Standard and reserved [scopes reference](/apis/openidoauth/scopes)
- Standard, custom, and reserved [claims reference](/apis/openidoauth/claims)

The [OIDC Playground](https://zitadel.com/playgrounds/oidc) is for testing OpenID authentication requests and their parameters.

### SAML 2.0

- [SAML 2.0 endpoints](/apis/saml/endpoints) definition
- [Custom attributes](https://github.com/zitadel/actions/blob/main/examples/set_custom_attribute.js) can be added with an action

### Custom

ZITADEL allows to authenticate users by creating a session with the [Session API](/reference/api/session), get OIDC authentication request details with the [OIDC service API](/reference/api/oidc) or get SAML request details with the [SAML service API](/reference/api/saml).
User authorizations can be [retrieved as roles from our APIs](/guides/integrate/retrieve-user-roles).

Refer to our guide to learn how to [build your own login UI](/guides/integrate/login-ui)

## ZITADEL APIs (resource-based)

ZITADEL provides APIs for each [core resource](/apis/v2):

- [User](/reference/api/user)
- [Session](/reference/api/session)
- [Settings](/reference/api/settings)

<Callout>
We are migrating to a resource-based API approach.
You might need to use the existing [service-based](#zitadel-apis-service-based) APIs for now to manage Organizations, Instances, Assets etc.
</Callout>

## ZITADEL APIs (service-based)

<Callout title="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](#zitadel-apis-resource-based).
</Callout>

<ApiCard title="Authentication" type="AUTH">
<Column>
<div>

### 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.

</div>
<div className="apicard-right">

#### Auth GRPC

Endpoint:
`${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/`

Definition:
[Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto)

#### Auth REST

Endpoint:
`${CUSTOM_DOMAIN}/auth/v1/`

API Reference:
[OpenAPI Docs](/reference/api/auth)

</div>
</Column>
</ApiCard>

<ApiCard title="Management" type="MGMT">
<Column>

<div>

### 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.

</div>
<div className="apicard-right">

#### Mgmt GRPC

Endpoint:
`${CUSTOM_DOMAIN}/zitadel.management.v1.ManagementService/`

Definition:
[Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto)

#### Mgmt REST

Endpoint:
`${CUSTOM_DOMAIN}/management/v1/`

API Reference:
[OpenAPI Docs](/reference/api/management)

</div>
</Column>
</ApiCard>

<ApiCard title="Administration" type="ADMIN">
<Column>
<div>

### Administration

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

</div>
<div className="apicard-right">

#### Admin GRPC

Endpoint:
`${CUSTOM_DOMAIN}/zitadel.admin.v1.AdminService/`

Definition:
[Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto)

#### Admin REST

Endpoint:
`${CUSTOM_DOMAIN}/admin/v1/`

API Reference:
[OpenAPI Docs](/reference/api/admin)

</div>
</Column>
</ApiCard>

<ApiCard title="Administration" type="SYSTEM">
<Column>
<div>

### System

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

Checkout the guide how to [access the ZITADEL System API](/guides/integrate/zitadel-apis/access-zitadel-system-api).

</div>
<div className="apicard-right">

#### System GRPC

Endpoint:
`${CUSTOM_DOMAIN}/zitadel.system.v1.SystemService/`

Definition:
[System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)

#### System REST

Endpoint:
`${CUSTOM_DOMAIN}/system/v1/`

API Reference:
[OpenAPI Docs](/reference/api/system)

</div>
</Column>
</ApiCard>

<ApiCard title="Assets" type="ASSET">
<Column>
<div>

### 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.

</div>
<div>

#### Assets REST

Endpoint:
`${CUSTOM_DOMAIN}/assets/v1/`

Definition:
[Assets](./assets/assets)

</div>
</Column>
</ApiCard>

## 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](/sdk-examples/introduction) 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](https://github.com/zitadel/zitadel/tree/main/proto/zitadel).

> More about [Protocol Buffer](https://developers.google.com/protocol-buffers)

### Example

See below for an example with the call **GetMyUser**.

```go
  //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    | `${CUSTOM_DOMAIN}/auth/v1/users/me`                      |
| GRPC    | `${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/GetMyUser` |

## Domains

ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your Custom Domain `${CUSTOM_DOMAIN}`

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

Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](/self-hosting/manage/custom-domain).

## 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.

```yaml
/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/
```
## Postman Collection (Beta)

We published an official Postman collection to help you explore and test the ZITADEL APIs.

The collection is organized by services, and includes a script to automatically authenticate requests. Before using it, make sure to configure the required environment variables in Postman:

| Variable Name           | Description |
|-------------------------|-------------|
| `protocol`          | **http** for local testing, or **https** for cloud/self hosted instances |
| `custom_domain`          | The domain of your Zitadel instance. |
| `service_client_id`     | Client ID of service account with **IAM_OWNER** role in your Zitadel instance. |
| `service_client_secret` | Client secret for the service account. |
| `api_client_id`         | Client ID of an API application. |
| `api_client_secret`     | Client secret for the API application. |
| `project_id`            | A project ID within your Zitadel instance. |

[Fork the Postman Collection](https://app.getpostman.com/run-collection/44392838-6417c238-b9b9-4334-bef0-233ae38cbc51?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D44392838-6417c238-b9b9-4334-bef0-233ae38cbc51%26entityType%3Dcollection%26workspaceId%3D54ef8cdd-5ea3-4f31-89f6-20720b45528c)

This release is currently in **beta**, and we welcome your feedback to improve it.