mirror of
https://github.com/zitadel/zitadel.git
synced 2025-04-20 13:01:32 +00:00
2bd3f44094
# Which Problems Are Solved The `/oauth/v1` path prefix is duplicated, which is an error in most proxies. # How the Problems Are Solved Remove the duplicate path prefix from the docs. Co-authored-by: Fabi <fabienne@zitadel.com>
322 lines
9.9 KiB
Plaintext
322 lines
9.9 KiB
Plaintext
---
|
|
title: ZITADEL API Reference Overview
|
|
sidebar_label: Overview
|
|
---
|
|
|
|
import { ApiCard } from "../../src/components/apicard";
|
|
import Column from "../../src/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](/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).
|
|
|
|
[Actions](/docs/apis/actions/introduction) allow to extend ZITADEL with custom code to change default behaviors or calling external systems.
|
|
|
|
## Authentication & authorization
|
|
|
|
### Authentication for human users (interactive)
|
|
|
|
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/login/login-users) through an interactive authentication process.
|
|
|
|
For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the [device authorization grant](/docs/guides/integrate/login/oidc/device-authorization).
|
|
|
|
Additionally, you can use the [session API](../apis/resources/session_service_v2/) to authenticate users, for example by building a [custom login UI](/docs/guides/integrate/login-ui/).
|
|
|
|
### Authenticate service users and machines
|
|
|
|
Service users allow for machine-to-machine (M2M) communication.
|
|
Follow the guides to learn how to [authenticate service users](/docs/guides/integrate/service-users/authenticate-service-users).
|
|
|
|
Accessing the ZITADEL APIs through a service user 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](/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 [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_v2) 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/v2):
|
|
|
|
- [User](/docs/apis/resources/user_service_v2)
|
|
- [Session](/docs/apis/resources/session_service_v2)
|
|
- [Settings](/docs/apis/resources/settings_service_v2)
|
|
|
|
:::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
|
|
|
|
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:
|
|
$ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/
|
|
|
|
Definition:
|
|
[Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto)
|
|
|
|
#### REST
|
|
|
|
Endpoint:
|
|
$ZITADEL_DOMAIN/auth/v1/
|
|
|
|
API Reference:
|
|
[OpenAPI Docs](/apis/resources/auth)
|
|
|
|
</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:
|
|
$ZITADEL_DOMAIN/zitadel.management.v1.ManagementService/
|
|
|
|
Definition:
|
|
[Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto)
|
|
|
|
#### REST
|
|
|
|
Endpoint:
|
|
$ZITADEL_DOMAIN/management/v1/
|
|
|
|
API Reference:
|
|
[OpenAPI Docs](/apis/resources/mgmt)
|
|
|
|
</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:
|
|
$ZITADEL_DOMAIN/zitadel.admin.v1.AdminService/
|
|
|
|
Definition:
|
|
[Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto)
|
|
|
|
#### REST
|
|
|
|
Endpoint:
|
|
$ZITADEL_DOMAIN/admin/v1/
|
|
|
|
API Reference:
|
|
[OpenAPI Docs](/apis/resources/admin)
|
|
|
|
</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](/docs/guides/integrate/zitadel-apis/access-zitadel-system-api).
|
|
|
|
</div>
|
|
<div className="apicard-right">
|
|
|
|
#### GRPC
|
|
|
|
Endpoint:
|
|
$ZITADEL_DOMAIN/zitadel.system.v1.SystemService/
|
|
|
|
Definition:
|
|
[System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
|
|
|
|
#### REST
|
|
|
|
Endpoint:
|
|
$ZITADEL_DOMAIN/system/v1/
|
|
|
|
API Reference:
|
|
[OpenAPI Docs](/apis/resources/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>
|
|
|
|
#### REST
|
|
|
|
Endpoint:
|
|
$ZITADEL_DOMAIN/assets/v1/
|
|
|
|
Definition:
|
|
[Assets](./assets/assets.md)
|
|
|
|
</div>
|
|
</Column>
|
|
</ApiCard>
|
|
|
|
|
|
## 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/sdk-examples/introduction) 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
|
|
//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 | $ZITADEL_DOMAIN/auth/v1/users/me |
|
|
| GRPC | $ZITADEL_DOMAIN/zitadel.auth.v1.AuthService/GetMyUser |
|
|
|
|
## Domains
|
|
|
|
ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or your custom domain `$ZITADEL_DOMAIN`
|
|
|
|
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/`.
|
|
|
|
Are you self-hosting and having troubles with *Instance not found* errors? [Check out this page](/docs/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.
|
|
|
|
```yaml
|
|
/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/
|
|
/device
|
|
/.well-known/openid-configuration
|
|
/openapi/
|
|
/idps/callback
|
|
/v2beta/
|
|
/zitadel.user.v2beta.UserService/
|
|
/zitadel.session.v2beta.SessionService/
|
|
/zitadel.settings.v2beta.SettingsService/
|
|
/zitadel.oidc.v2beta.OIDCService/
|
|
/zitadel.org.v2beta.OrganizationService/
|
|
/v2/
|
|
/zitadel.user.v2.UserService/
|
|
/zitadel.session.v2.SessionService/
|
|
/zitadel.settings.v2.SettingsService/
|
|
/zitadel.oidc.v2.OIDCService/
|
|
/zitadel.org.v2.OrganizationService/
|
|
```
|