diff --git a/docs/docs/apis/apis.md b/docs/docs/apis/apis.md deleted file mode 100644 index 65aa252fee..0000000000 --- a/docs/docs/apis/apis.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: ZITADEL APIs ---- - -## Overview - -![API Overview](/img/api/apis_overview.png) - -## 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/) | diff --git a/docs/docs/apis/domains.md b/docs/docs/apis/domains.md deleted file mode 100644 index 4df491e52d..0000000000 --- a/docs/docs/apis/domains.md +++ /dev/null @@ -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 | diff --git a/docs/docs/apis/introduction.md b/docs/docs/apis/introduction.md deleted file mode 100644 index d4f582b132..0000000000 --- a/docs/docs/apis/introduction.md +++ /dev/null @@ -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) | diff --git a/docs/docs/apis/introduction.mdx b/docs/docs/apis/introduction.mdx new file mode 100644 index 0000000000..f84f0b6da7 --- /dev/null +++ b/docs/docs/apis/introduction.mdx @@ -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/) + + + +
+ +## 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: +[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) + + +
+ + + + + + +
+ +## 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: +[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) + +
+ + + + + +
+ +## Administration + +This API is intended to configure and manage the IAM itself. + +
+
+ +### 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) + +
+ + + + + +
+ +## 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: +[https://api.zitadel.ch/assets/v1/](https://api.zitadel.ch/assets/v1/) + +Definition: +[/docs/apis/assets/assets](/docs/apis/assets/assets) + + +
+ + + +## 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 | diff --git a/docs/docs/guides/installation/crd.md b/docs/docs/guides/installation/crd.md index a3512bc1ef..5b4a6cb78c 100644 --- a/docs/docs/guides/installation/crd.md +++ b/docs/docs/guides/installation/crd.md @@ -64,4 +64,4 @@ kubectl apply --filename ./boom.yml watch "kubectl --namespace caos-system get pods" ``` -Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/domains) now. +Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/introduction#domains) now. diff --git a/docs/docs/guides/installation/gitops.md b/docs/docs/guides/installation/gitops.md index 622cfe43b0..03dbb60f10 100644 --- a/docs/docs/guides/installation/gitops.md +++ b/docs/docs/guides/installation/gitops.md @@ -52,4 +52,4 @@ orbctl --gitops takeoff watch "kubectl --namespace caos-system get pods" ``` -Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/domains) now. +Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/introduction#domains) now. diff --git a/docs/docs/guides/installation/managed-dedicated-instance.md b/docs/docs/guides/installation/managed-dedicated-instance.md index d50c779170..2fa8fc3925 100644 --- a/docs/docs/guides/installation/managed-dedicated-instance.md +++ b/docs/docs/guides/installation/managed-dedicated-instance.md @@ -56,7 +56,7 @@ import TabItem from '@theme/TabItem'; -- We need you to point [four DNS subdomains](/docs/apis/domains) to the CAOS-generated IP address. +- We need you to point [four DNS subdomains](/docs/apis/introduction#domains) to the CAOS-generated IP address. - For being able to send SMS, we need a Twilio sender name, SID and an auth token. - ZITADEL also needs to connect to an email relay of your choice. We need the SMTP host, user and app key as well as the ZITADEL emails sender address and name. diff --git a/docs/docs/quickstarts/login/angular.md b/docs/docs/quickstarts/login/angular.md index e5da3c6af0..e75a7e5df1 100644 --- a/docs/docs/quickstarts/login/angular.md +++ b/docs/docs/quickstarts/login/angular.md @@ -300,6 +300,6 @@ If you get stuck consider checking out our [template](https://github.com/caos/zi ### Whats next? -Now you can proceed implementing our APIs to include Authorization. Refer to our [Docs](../../apis/apis) or checkout our Console Code on [Github](https://github.com/caos/zitadel) which is using GRPC to access data. +Now you can proceed implementing our APIs to include Authorization. Refer to our [Docs](../../apis/introduction) or checkout our Console Code on [Github](https://github.com/caos/zitadel) which is using GRPC to access data. For more information about creating an angular application we refer to [Angular](https://angular.io/start) and for more information about the used oauth/oidc library consider reading their docs at [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc). diff --git a/docs/docs/quickstarts/login/react.md b/docs/docs/quickstarts/login/react.md index e6876a109b..d6232d8467 100644 --- a/docs/docs/quickstarts/login/react.md +++ b/docs/docs/quickstarts/login/react.md @@ -110,6 +110,6 @@ You have successfully integrated ZITADEL in your React Application! ### Whats next? -Now you can proceed implementing our APIs to include Authorization. You can find our API Docs [here](../../apis/apis) +Now you can proceed implementing our APIs to include Authorization. You can find our API Docs [here](../../apis/introduction) For more information about creating a React application we refer to [React](https://reactjs.org/docs/getting-started.html) and for more information about the used oauth/oidc library consider reading their docs at [oidc-react](https://www.npmjs.com/package/oidc-react). diff --git a/docs/sidebars.js b/docs/sidebars.js index 6698a0c432..decd0d0300 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -130,47 +130,42 @@ module.exports = { ], apis: [ 'apis/introduction', - 'apis/domains', { type: 'category', - label: 'Rate Limits', + label: 'API Definition', collapsed: true, items: [ - 'legal/rate-limit-policy', - 'apis/ratelimits/accounts', - 'apis/ratelimits/api', - ], - }, - 'apis/apis', - { - type: 'category', - label: 'Proto API Definition', - collapsed: true, - items: [ - 'apis/proto/auth', - 'apis/proto/management', - 'apis/proto/admin', - 'apis/proto/org', - 'apis/proto/user', - 'apis/proto/app', - 'apis/proto/policy', - 'apis/proto/auth_n_key', - 'apis/proto/change', - 'apis/proto/idp', - 'apis/proto/member', - 'apis/proto/metadata', - 'apis/proto/message', - 'apis/proto/text', - 'apis/proto/object', - 'apis/proto/options', - ], - }, - { - type: 'category', - label: 'Assets API Definition', - collapsed: false, - items: [ - 'apis/assets/assets', + { + type: 'category', + label: 'Proto', + collapsed: true, + items: [ + 'apis/proto/auth', + 'apis/proto/management', + 'apis/proto/admin', + 'apis/proto/org', + 'apis/proto/user', + 'apis/proto/app', + 'apis/proto/policy', + 'apis/proto/auth_n_key', + 'apis/proto/change', + 'apis/proto/idp', + 'apis/proto/member', + 'apis/proto/metadata', + 'apis/proto/message', + 'apis/proto/text', + 'apis/proto/object', + 'apis/proto/options' + ], + }, + { + type: 'category', + label: 'Assets API', + collapsed: true, + items: [ + 'apis/assets/assets', + ], + }, ], }, { @@ -185,6 +180,16 @@ module.exports = { 'apis/openidoauth/grant-types' ], }, + { + type: 'category', + label: 'Rate Limits', + collapsed: true, + items: [ + 'legal/rate-limit-policy', + 'apis/ratelimits/accounts', + 'apis/ratelimits/api', + ], + }, ], concepts: [ 'concepts/introduction', diff --git a/docs/src/components/apicard.jsx b/docs/src/components/apicard.jsx new file mode 100644 index 0000000000..c6b0e1be0f --- /dev/null +++ b/docs/src/components/apicard.jsx @@ -0,0 +1,31 @@ +import React from 'react'; + +import styles from '../css/apicard.module.css'; + +export function ApiCard({ title, type, label, children}) { + let style = styles.apiauth; + switch (type) { + case 'AUTH': + style = styles.apiauth; + break; + case 'MGMT': + style = styles.apimgmt; + break; + case 'ADMIN': + style = styles.apiadmin; + break; + case 'ASSET': + style = styles.apiasset; + break; + } + + return ( +
+ {/* {title &&

{title}

} */} + {/*

+ +

*/} + {children} +
+ ) +} diff --git a/docs/src/css/apicard.module.css b/docs/src/css/apicard.module.css new file mode 100644 index 0000000000..14e08b251d --- /dev/null +++ b/docs/src/css/apicard.module.css @@ -0,0 +1,73 @@ +.apicard { + border-radius: .5rem; + display: flex; + flex-direction: column; + min-width: 200px; + background: var(--card-background); + padding: 1rem; + text-decoration: none; + transition: all .2 ease-in-out; + margin: 1rem 0; +} + +.apiauth { + background: var(--apiauthbackground); +} + +.apimgmt { + background: var(--apimgmtbackground); +} + +.apiadmin { + background: var(--apiadminbackground); +} + +.apiasset { + background: var(--apiassetbackground); +} + +.apicard:hover { + text-decoration: none; + box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06); +} + +/* .apicard h2 { + color: white; +} + +.apicard a { + color: #bfc1cc; +} */ + +.apicard h3, h4, h5 { + /* color: white; */ + margin: 0.5rem 0 0 0; +} + +.apicard p { + font-size: 14px; + margin: 0; +} + +.fillspace { + flex: 1; +} + +.bottom { + display: flex; + align-items: center; +} + +.bottomicon { + width: 24px; + margin-right: .5rem; + color: var(--ifm-font-color-base); +} + +.bottomspan { + font-size: 12px; + font-weight: 600; + color: var(--ifm-font-color-base); + text-transform: uppercase; + margin: 0; +} diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index f9313a93a1..4f1e3975ca 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -54,6 +54,15 @@ --card-background: #fafafa; --list-background: #f7fafc; --ifm-spacing-horizontal: 1.5rem; + --apiauthbackground: linear-gradient(40deg, #a9d9ca 30%, #b4d5cb); + --apimgmtbackground: linear-gradient(40deg, #c6d7f3 30%, #c7c6e3); + --apiadminbackground: linear-gradient(40deg, #c192c790, #c192c790); + --apiassetbackground: linear-gradient(40deg, #e4eaf1, #eef2f9); +} + +.apicard-right { + overflow: hidden; + text-overflow: ellipsis; } .padding-top--md { @@ -198,6 +207,10 @@ h2 { --ifm-color-warning-contrast-foreground: #ffc1c1; --card-background: #454a66; --list-background: #3c405850; + --apiauthbackground: linear-gradient(40deg, #506e6e90 30%, #506e6e90); + --apimgmtbackground: linear-gradient(40deg, #595d8090 30%, #595d8090); + --apiadminbackground: linear-gradient(40deg, #6a506e90, #6a506e90); + --apiassetbackground: linear-gradient(40deg, #3c4257, #3c4257); } .menu li li a {