mirror of
https://github.com/zitadel/zitadel.git
synced 2025-01-06 13:07:52 +00:00
docs(api): restructure overview (#6485)
* update sdks * restructure * resource based * headings * docs: add sdks * docs: build your own login sidebar * Apply suggestions from code review Co-authored-by: Fabi <fabienne@zitadel.com> * add info * move custom login guide inline --------- Co-authored-by: Fabienne <fabienne.gerschwiler@gmail.com> Co-authored-by: Fabi <fabienne@zitadel.com>
This commit is contained in:
mffap
GitHub
parent
e844c6834c
commit
5541e0170c
@ -6,38 +6,72 @@ sidebar_label: Overview
|
||||
import { ApiCard } from "../../src/components/apicard";
|
||||
import Column from "../../src/components/column";
|
||||
|
||||
## APIs
|
||||
ZITADEL exposes all features via different gRPC and REST APIs and provides SDKs for popular languages and frameworks.
|
||||
|
||||
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.
|
||||
The [OpenID Connect & OAuth endpoints](/docs/apis/openidoauth/endpoints) and [SAML 2.0 endpoints](/docs/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).
|
||||
|
||||
### Proto
|
||||
[Actions](/docs/apis/actions/introduction) allow to extend ZITADEL with custom code to change default behaviors or calling external systems.
|
||||
|
||||
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).
|
||||
## Authentication & authorization
|
||||
|
||||
> More about [Protocol Buffer](https://developers.google.com/protocol-buffers)
|
||||
ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication.
|
||||
Please refer to our guides how to [authenticate users](/docs/guides/integrate/human-users) through an interactive authentication process and how to [authenticate service users](/docs/guides/integrate/serviceusers) with a programmatic authentication.
|
||||
|
||||
### Swagger Documentation
|
||||
### OpenID Connect & OAuth
|
||||
|
||||
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/)
|
||||
- [OpenID Connect endpoints](/docs/apis/openidoauth/endpoints) definition
|
||||
- Standard and reserved [scopes reference](/docs/apis/openidoauth/scopes)
|
||||
- Standard, custom, and reserved [claims reference](/docs/apis/openidoauth/claims)
|
||||
|
||||
The easiest way to have a look at them is, to import them in the [Swagger Editor](https://editor.swagger.io/)
|
||||
The [OIDC Playground](/docs/apis/openidoauth/authrequest) is for testing OpenID authentication requests and their parameters.
|
||||
|
||||
### SAML 2.0
|
||||
|
||||
- [SAML 2.0 endpoints](/docs/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](/docs/apis/resources/session_service) or get OIDC authentication request details with the [OIDC service API](/docs/apis/resources/oidc_service).
|
||||
User authorizations can be [retrieved as roles from our APIs](/docs/guides/integrate/retrieve-user-roles).
|
||||
|
||||
Refer to our guide to learn how to [build your own login UI](/docs/guides/integrate/login-ui)
|
||||
|
||||
## ZITADEL APIs (resource-based)
|
||||
|
||||
ZITADEL provides APIs for each [core resource](/docs/apis/resources):
|
||||
|
||||
- [User](/docs/apis/resources/user_service)
|
||||
- [Session](/docs/apis/resources/session_service)
|
||||
- [Settings](/docs/apis/resources/settings_service)
|
||||
|
||||
:::info
|
||||
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.
|
||||
:::
|
||||
|
||||
## ZITADEL APIs (service-based)
|
||||
|
||||
:::info 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).
|
||||
:::
|
||||
|
||||
<ApiCard title="Authentication" type="AUTH">
|
||||
<Column>
|
||||
<div>
|
||||
|
||||
## Authentication
|
||||
### 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
|
||||
#### GRPC
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/
|
||||
@ -45,7 +79,7 @@ $ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/
|
||||
Definition:
|
||||
[Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto)
|
||||
|
||||
### REST
|
||||
#### REST
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/auth/v1/
|
||||
@ -62,7 +96,7 @@ API Reference:
|
||||
|
||||
<div>
|
||||
|
||||
## Management
|
||||
### 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.
|
||||
@ -70,7 +104,7 @@ To identify the current organization you can send a header `x-zitadel-orgid` or
|
||||
</div>
|
||||
<div className="apicard-right">
|
||||
|
||||
### GRPC
|
||||
#### GRPC
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/zitadel.management.v1.ManagementService/
|
||||
@ -78,7 +112,7 @@ $ZITADEL_DOMAIN/zitadel.management.v1.ManagementService/
|
||||
Definition:
|
||||
[Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto)
|
||||
|
||||
### REST
|
||||
#### REST
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/management/v1/
|
||||
@ -94,14 +128,14 @@ API Reference:
|
||||
<Column>
|
||||
<div>
|
||||
|
||||
## Administration
|
||||
### Administration
|
||||
|
||||
This API is intended to configure and manage one ZITADEL instance itself.
|
||||
|
||||
</div>
|
||||
<div className="apicard-right">
|
||||
|
||||
### GRPC
|
||||
#### GRPC
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/zitadel.admin.v1.AdminService/
|
||||
@ -109,7 +143,7 @@ $ZITADEL_DOMAIN/zitadel.admin.v1.AdminService/
|
||||
Definition:
|
||||
[Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto)
|
||||
|
||||
### REST
|
||||
#### REST
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/admin/v1/
|
||||
@ -125,7 +159,7 @@ API Reference:
|
||||
<Column>
|
||||
<div>
|
||||
|
||||
## System
|
||||
### System
|
||||
|
||||
This API is intended to manage the different ZITADEL instances within the system.
|
||||
|
||||
@ -134,7 +168,7 @@ Checkout the guide how to [access the ZITADEL System API](/guides/integrate/acce
|
||||
</div>
|
||||
<div className="apicard-right">
|
||||
|
||||
### GRPC
|
||||
#### GRPC
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/zitadel.system.v1.SystemService/
|
||||
@ -142,7 +176,7 @@ $ZITADEL_DOMAIN/zitadel.system.v1.SystemService/
|
||||
Definition:
|
||||
[System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
|
||||
|
||||
### REST
|
||||
#### REST
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/system/v1/
|
||||
@ -158,14 +192,14 @@ API Reference:
|
||||
<Column>
|
||||
<div>
|
||||
|
||||
## Assets
|
||||
### 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
|
||||
#### REST
|
||||
|
||||
Endpoint:
|
||||
$ZITADEL_DOMAIN/assets/v1/
|
||||
@ -177,11 +211,36 @@ Definition:
|
||||
</Column>
|
||||
</ApiCard>
|
||||
|
||||
## Example
|
||||
|
||||
## 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](/docs/examples/sdks) 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)
|
||||
|
||||
### 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/)
|
||||
|
||||
### Example
|
||||
|
||||
See below for an example with the call **GetMyUser**.
|
||||
|
||||
```Go
|
||||
```go
|
||||
//User
|
||||
rpc GetMyUser(google.protobuf.Empty) returns (UserView) {
|
||||
option (google.api.http) = {
|
||||
@ -207,19 +266,14 @@ In the table below you can see the URI of those calls.
|
||||
|
||||
ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your custom domain `$ZITADEL_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
|
||||
## 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/
|
||||
@ -235,4 +289,8 @@ For easy copying to your reverse proxy configuration, here is the list of URL pa
|
||||
/oauth/v2/
|
||||
/.well-known/openid-configuration
|
||||
/openapi/
|
||||
/v2alpha/
|
||||
/zitadel.user.v2alpha.UserService/
|
||||
/zitadel.session.v2alpha.SessionService/
|
||||
/zitadel.settings.v2alpha.SettingsService/
|
||||
```
|
||||
|
||||
@ -2,18 +2,23 @@
|
||||
title: SDKs
|
||||
---
|
||||
|
||||
## ZITADEL SDK
|
||||
On this page you find our official SDKs, links to supporting frameworks and providers, and resources to help with SDKs.
|
||||
The SDKs wrap either our [gRPC or REST APIs](/docs/apis/introduction) to provide the client with User Authentication and Management for resources.
|
||||
|
||||
| Language / Framework | Link Github | User Authentication | Manage resources | Notes |
|
||||
|--- | --- | --- | --- | --- |
|
||||
| .NET | [zitadel-net](https://github.com/smartive/zitadel-net) | ✔️ | ✔️ | `community` |
|
||||
| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | ✔️ | ✔️ | `community` |
|
||||
| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | ❌ | ✔️ | `official` |
|
||||
| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | TBD |
|
||||
| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | TBD |
|
||||
| NodeJS | [@zitadel/node](https://www.npmjs.com/package/@zitadel/node) | ❌ | ✔️ | `community` |
|
||||
## ZITADEL SDKs
|
||||
|
||||
## Missing an SDK
|
||||
| Language / Framework | Link Github | User Authentication | Manage resources | Notes |
|
||||
|----------------------|---------------------------------------------------------------| --- | --- | --- |
|
||||
| .NET | [zitadel-net](https://github.com/smartive/zitadel-net) | ✔️ | ✔️ | `community` |
|
||||
| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | ✔️ | ✔️ | `community` |
|
||||
| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | ❌ | ✔️ | `official` |
|
||||
| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | TBD |
|
||||
| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | TBD |
|
||||
| NodeJS | [@zitadel/node](https://www.npmjs.com/package/@zitadel/node) | ❌ | ✔️ | `community` |
|
||||
| Dart | [zitadel-dart](https://github.com/smartive/zitadel-dart) | ❌ | ✔️ | `community` |
|
||||
| Rust | [zitadel-rust](https://github.com/smartive/zitadel-rust) | ✔️ | ✔️ | `community` |
|
||||
|
||||
## Missing SDK
|
||||
|
||||
Is your language/framework missing? Fear not, you can generate your gRPC API Client with ease.
|
||||
|
||||
@ -83,7 +88,6 @@ Import these files into your project to start interacting with ZITADEL's APIs.
|
||||
While we are not actively maintaining the following projects, it is worth checking out if you're interested in exploring ZITADEL in different programming languages or frameworks.
|
||||
|
||||
- [NodeJS passport](https://github.com/buehler/node-passport-zitadel) authentication helper
|
||||
- [Dart library for ZITADEL](https://github.com/smartive/zitadel-dart), contains gRPC and API access elements
|
||||
- [NextAuth Provider for ZITADEL](https://next-auth.js.org/providers/zitadel)
|
||||
|
||||
If we do not provide an example, SDK or guide, we strongly recommend using existing authentication libraries for your language or framework instead of building your own.
|
||||
|
||||
@ -144,6 +144,13 @@ module.exports = {
|
||||
type: "category",
|
||||
label: "Authenticate users",
|
||||
collapsed: true,
|
||||
link: {
|
||||
type: "generated-index",
|
||||
title: "Authenticate human users",
|
||||
slug: "guides/integrate/human-users",
|
||||
description:
|
||||
"How to authenticate human users with OpenID Connect",
|
||||
},
|
||||
items: [
|
||||
"guides/integrate/login-users",
|
||||
"guides/integrate/oauth-recommended-flows",
|
||||
@ -439,6 +446,13 @@ module.exports = {
|
||||
type: "category",
|
||||
label: "Core Resources",
|
||||
collapsed: false,
|
||||
link: {
|
||||
type: "generated-index",
|
||||
title: "Core Resources",
|
||||
slug: "/apis/resources/",
|
||||
description:
|
||||
"Resource based API definitions",
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: "category",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user