mirror of
https://github.com/zitadel/zitadel.git
synced 2025-12-05 10:52:04 +00:00
docs(apis): cleanup navigation, better overview (#2608)
* api cards, cleanup overview * endpoint, definition shortcuts, links * update quickstart links * mobile overflow * Update docs/docs/apis/introduction.mdx Co-authored-by: Florian Forster <florian@caos.ch> * Update docs/docs/apis/introduction.mdx Co-authored-by: Florian Forster <florian@caos.ch> Co-authored-by: Florian Forster <florian@caos.ch>
This commit is contained in:
Max Peintner
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: ZITADEL APIs
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
|
||||
## Proto
|
||||
|
||||
All of our APIs are generated by proto defintions. 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://api.zitadel.ch/openapi/v2/swagger/](https://api.zitadel.ch/openapi/v2/swagger/)
|
||||
The easiest way to have a look at them is, to import them in the [Swagger Editor](https://editor.swagger.io/)
|
||||
|
||||
## Authentication API aka Auth
|
||||
|
||||
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.
|
||||
|
||||
| Service | URI |
|
||||
|:--------|:----------------------------------------------------------------------------------------------------------------------------|
|
||||
| REST | [https://api.zitadel.ch/auth/v1/](https://api.zitadel.ch/auth/v1/) |
|
||||
| GRPC | [https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService) |
|
||||
|
||||
> At a later date we might expose functions to build your own login GUI
|
||||
> You can build your own user Register GUI already by utilizing the [Management API](#management)
|
||||
|
||||
[Latest API Version](https://github.com/caos/zitadel/blob/main/proto/zitadel/auth.proto)
|
||||
|
||||
|
||||
## Management API
|
||||
|
||||
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.
|
||||
|
||||
| Service | URI |
|
||||
|:--------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| REST | [https://api.zitadel.ch/management/v1/](https://api.zitadel.ch/management/v1/) |
|
||||
| GRPC | [https://api.zitadel.ch/caos.zitadel.management.api.v1.ManagementService/](https://api.zitadel.ch/caos.zitadel.management.api.v1.ManagementService) |
|
||||
|
||||
[Latest API Version](https://github.com/caos/zitadel/blob/main/proto/zitadel/management.proto)
|
||||
|
||||
|
||||
## Administration API aka Admin
|
||||
|
||||
This API is intended to configure and manage the IAM itself.
|
||||
|
||||
| Service | URI |
|
||||
|:--------|:--------------------------------------------------------------------------------------------------------------------------------|
|
||||
| REST | [https://api.zitadel.ch/admin/v1/](https://api.zitadel.ch/admin/v1/) |
|
||||
| GRPC | [https://api.zitadel.ch/caos.zitadel.admin.api.v1.AdminService/](https://api.zitadel.ch/caos.zitadel.admin.api.v1.AdminService) |
|
||||
|
||||
[Latest API Version](https://github.com/caos/zitadel/blob/main/proto/zitadel/admin.proto)
|
||||
|
||||
## Assets API
|
||||
|
||||
|
||||
The Assets API allows you to up- and download all kinds of assets. This can be files such as logos, fonts or user avatar.
|
||||
|
||||
|
||||
| Service | URI |
|
||||
|:--------|:--------------------------------------------------------------------------------------------------------------------------------|
|
||||
| REST | [https://api.zitadel.ch/assets/v1/](https://api.zitadel.ch/assets/v1/) |
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
title: Domains
|
||||
---
|
||||
|
||||
| Domain Name | Example | Description |
|
||||
| :---------- | :-------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| issuer | `issuer.zitadel.ch` | Provides the [OpenID Connect 1.0 Discovery Endpoint](openidoauth/endpoints#openid-connect-10-discovery) |
|
||||
| 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 |
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
## APIs
|
||||
|
||||
---
|
||||
|
||||
ZITADEL provides four API's for different use cases. Three API's are built with GRPC and then 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 we use multipart form data.
|
||||
|
||||
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 (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](https://api.zitadel.ch/auth/v1/users/me) |
|
||||
| GRPC | [https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser) |
|
||||
172
docs/docs/apis/introduction.mdx
Normal file
172
docs/docs/apis/introduction.mdx
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
title: Overview
|
||||
---
|
||||
|
||||
import {ApiCard} from '../../src/components/apicard';
|
||||
import Column from '../../src/components/column';
|
||||
|
||||
## 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](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://api.zitadel.ch/openapi/v2/swagger/](https://api.zitadel.ch/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 class="apicard-right">
|
||||
|
||||
### GRPC
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService)
|
||||
|
||||
Definition:
|
||||
[Auth Proto](/docs/apis/proto/auth)
|
||||
|
||||
### REST
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/auth/v1/](https://api.zitadel.ch/auth/v1/)
|
||||
|
||||
Definition:
|
||||
[Swagger Definition](https://api.zitadel.ch/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 class="apicard-right">
|
||||
|
||||
### GRPC
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService)
|
||||
|
||||
Definition:
|
||||
[Management Proto](/docs/apis/proto/management)
|
||||
|
||||
### REST
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/management/v1/](https://api.zitadel.ch/management/v1/)
|
||||
|
||||
Definition:
|
||||
[Swagger Definition](https://api.zitadel.ch/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 the IAM itself.
|
||||
|
||||
</div>
|
||||
<div class="apicard-right">
|
||||
|
||||
### GRPC
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/](https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService)
|
||||
|
||||
Definition:
|
||||
[Admin Proto](/docs/apis/proto/auth)
|
||||
|
||||
### REST
|
||||
Endpoint:
|
||||
[https://api.zitadel.ch/admin/v1/](https://api.zitadel.ch/admin/v1/)
|
||||
|
||||
Definition:
|
||||
[Swagger Definition](https://api.zitadel.ch/openapi/v2/swagger/admin.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:
|
||||
[https://api.zitadel.ch/assets/v1/](https://api.zitadel.ch/assets/v1/)
|
||||
|
||||
Definition:
|
||||
[/docs/apis/assets/assets](/docs/apis/assets/assets)
|
||||
|
||||
|
||||
</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 (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](https://api.zitadel.ch/auth/v1/users/me) |
|
||||
| GRPC | [https://api.zitadel.ch/caos.zitadel.auth.api.v1.AuthService/GetMyUser](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](openidoauth/endpoints#openid-connect-10-discovery) |
|
||||
| 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 |
|
||||
Reference in New Issue
Block a user