---
title: ZITADEL API Reference Overview
description: "Explore ZITADEL's APIs for authentication and authorization. Integrate identity management using OpenID Connect, OAuth 2.0, and SAML standards."
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).

[Actions](/guides/manage/console/actions-overview) allow extending ZITADEL with custom code to change default behaviors or calling external systems.

## Authentication & Authorization

### Authentication for users (interactive)

ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication.
Please refer to our guides on how to [authenticate users](/guides/integrate/login/login-users) through an interactive authentication process.

For user authentication on devices with limited accessibility (eg, SmartTV, Smartwatch, 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 accounts

Service accounts allow for machine-to-machine (M2M) communication.
Follow the guides to learn how to [authenticate service accounts](/guides/integrate/service-accounts/authenticate-service-accounts).

Accessing the ZITADEL APIs through a service account 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

### Session-based and custom login

For building a custom login flow, you have access to purpose-built v2 APIs:

- [Create or update a session](/reference/api/session/zitadel.session.v2.SessionService.CreateSession) to authenticate users step by step
- [Get OIDC auth request details](/reference/api/oidc/zitadel.oidc.v2.OIDCService.GetAuthRequest) when acting as an OIDC provider
- [Get SAML request details](/reference/api/saml/zitadel.saml.v2.SAMLService.GetSAMLRequest) when acting as a SAML provider

User role assignments 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

**Use the [v2 APIs](/apis/v2) for all new integrations.** They are the recommended, resource-based API surface for ZITADEL and where all new development is happening.
The v1 APIs are legacy: fully supported and still required in some places, but not being extended.

If the resource you need is not yet available in v2, use the corresponding legacy v1 API for that operation and check the [migration guide](/apis/migration_v1_to_v2) to plan your transition.

## APIs v2 (resource-based)

ZITADEL provides v2 APIs for the following resources:

- [User](/reference/api/user) — manage users and their authentication methods
- [Session](/reference/api/session) — create and manage user sessions
- [Organization](/reference/api/org) — manage organizations
- [Instance](/reference/api/instance) — manage your ZITADEL instance
- [Project](/reference/api/project) — manage projects and granted projects
- [Application](/reference/api/application) — manage OIDC, SAML, and API applications
- [IDP](/reference/api/idp) — manage identity providers
- [Group](/reference/api/group) — manage user groups
- [Settings](/reference/api/settings) — read login and instance settings
- [Feature](/reference/api/feature) — manage feature flags
- [Authorization](/reference/api/authorization) — check and manage user permissions
- [Action](/reference/api/action) — manage execution targets and action flows
- [WebKey](/reference/api/webkey) — manage signing keys
- [OIDC](/reference/api/oidc) — handle OIDC authorization flows (used when building a custom login UI)
- [SAML](/reference/api/saml) — handle SAML authorization flows (used when building a custom login UI)

Not finding a resource here? It has not yet been migrated to v2 — use the legacy v1 APIs below for that operation.

## Legacy v1 APIs

The following APIs predate the v2 resource-based design. They are still fully supported and required for capabilities not yet covered by v2, but they are no longer being extended. If you are building something new, check the v2 section above first.

Looking to move an existing integration off v1? See the [v1 to v2 migration guide](/apis/migration_v1_to_v2).

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

### Authentication

The Auth API covers operations on the currently authenticated user. The user is identified from the `sub` claim in the access token.

For new integrations, prefer the [User v2 API](/reference/api/user) and [Session v2 API](/reference/api/session) which provide the same capabilities in a resource-based design.

</div>
<div className="apicard-right min-w-0 overflow-x-auto [&_code]:!whitespace-nowrap">

#### 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 lets systems read and mutate resources within an organization — users, projects, applications, roles, and more. The target organization is determined by the `x-zitadel-orgid` request header, or falls back to the organization of the authenticated user.

For new integrations, prefer the [User v2 API](/reference/api/user) for user management, which handles both instance-level and organization-level access automatically based on caller permissions.

</div>
<div className="apicard-right min-w-0 overflow-x-auto [&_code]:!whitespace-nowrap">

#### 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 min-w-0 overflow-x-auto [&_code]:!whitespace-nowrap">

#### 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="System" 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 min-w-0 overflow-x-auto [&_code]:!whitespace-nowrap">

#### 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](/apis/assets/assets)

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

## Client libraries & schemas

ZITADEL publishes [official and community-supported SDKs](/sdk-examples/introduction) for multiple languages and frameworks.
All API services are defined as [proto definitions on GitHub](https://github.com/zitadel/zitadel/tree/main/proto/zitadel) — most languages let you generate a type-safe client directly from them.

## 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 Management Console (`${CUSTOM_DOMAIN}/ui/console/`), and the hosted Login UI (`${CUSTOM_DOMAIN}/ui/v2/login`).

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.

```
# v2 APIs (recommended for new integrations)
# REST (HTTP/JSON transcoding):
/v2/
# gRPC + Connect protocol (binary or JSON via connectRPC):
/zitadel.action.v2.ActionService/
/zitadel.application.v2.ApplicationService/
/zitadel.authorization.v2.AuthorizationService/
/zitadel.feature.v2.FeatureService/
/zitadel.group.v2.GroupService/
/zitadel.idp.v2.IdentityProviderService/
/zitadel.instance.v2.InstanceService/
/zitadel.oidc.v2.OIDCService/
/zitadel.org.v2.OrganizationService/
/zitadel.project.v2.ProjectService/
/zitadel.saml.v2.SAMLService/
/zitadel.session.v2.SessionService/
/zitadel.settings.v2.SettingsService/
/zitadel.user.v2.UserService/
/zitadel.webkey.v2.WebKeyService/

# v2beta — kept for backward compatibility, use /v2/ for new work
/v2beta/

# Legacy v1 APIs
/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/

# OpenID Connect, OAuth 2.0, SAML 2.0 & standards
/oidc/v1/
/saml/v2/
/oauth/v2/
/device
/.well-known/openid-configuration
/openapi/
/idps/callback

# UIs
/ui/console/  # Management Console (Angular admin UI)
/ui/v2/login  # Login UI v2 (Next.js; routes to a separate container in self-hosted deployments)
/ui/login/    # Login UI v1 (legacy, built into the ZITADEL binary)
```
## 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.