zitadel/docs/docs/apis/introduction.mdx

---
title: Overview
---

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

## APIs

ZITADEL provides five APIs for different use cases. Four 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 definitions. You can find all the proto definitions in the [Proto API Definitions](proto/auth).

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

### Swagger Documentation

We provide some json files for the swagger documentation of our APIs with the following link: [https://zitadel.cloud/openapi/v2/swagger/](https://zitadel.cloud/openapi/v2/swagger/)

The easiest way to have a look at them is, to import them in the [Swagger Editor](https://editor.swagger.io/)

<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">

### GRPC

Endpoint:
{your_domain}/zitadel.auth.v1.AuthService/

Definition:
[Auth Proto](/apis/proto/auth)

### REST

Endpoint:
{your_domain}/auth/v1/

Swagger Editor:
[editor.swagger.io](https://editor.swagger.io/?url=https://zitadel.cloud/openapi/v2/swagger/auth.swagger.json)

Definition:
[Swagger Definition](https://zitadel.cloud/openapi/v2/swagger/auth.swagger.json)

</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">

### GRPC

Endpoint:
{your_domain}/zitadel.management.v1.ManagementService/

Definition:
[Management Proto](/apis/proto/management)

### REST

Endpoint:
{your_domain}/management/v1/

Swagger Editor:
[editor.swagger.io](https://editor.swagger.io/?url=https://zitadel.cloud/openapi/v2/swagger/management.swagger.json)

Definition:
[Swagger Definition](https://zitadel.cloud/openapi/v2/swagger/management.swagger.json)

</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">

### GRPC

Endpoint:
{your_domain}/zitadel.admin.v1.AdminService/

Definition:
[Admin Proto](/apis/proto/admin)

### REST

Endpoint:
{your_domain}/admin/v1/

Swagger Editor:
[editor.swagger.io](https://editor.swagger.io/?url=https://zitadel.cloud/openapi/v2/swagger/admin.swagger.json)

Definition:
[Swagger Definition](https://zitadel.cloud/openapi/v2/swagger/admin.swagger.json)

</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/access-zitadel-system-api).

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

### GRPC

Endpoint:
{your_domain}/zitadel.system.v1.SystemService/

Definition:
[System Proto](/apis/proto/system)

### REST

Endpoint:
{your_domain}/system/v1/

Swagger Editor:
[editor.swagger.io](https://editor.swagger.io/?url=https://zitadel.cloud/openapi/v2/swagger/system.swagger.json)

Definition:
[Swagger Definition](https://zitadel.cloud/openapi/v2/swagger/system.swagger.json)

</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>

### REST

Endpoint:
{your_domain}/assets/v1/

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

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

## 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    | {your_domain}/auth/v1/users/me                      |
| GRPC    | {your_domain}/zitadel.auth.v1.AuthService/GetMyUser |

## Domains

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

:::note
Changes from ZITADEL V1:
Be aware that issuer, api, accounts and console domains do not exist anymore.
:::

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/`.

## ZITADEL 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/
/.well-known/openid-configuration
/openapi/
```