# Which Problems Are Solved
As part of https://github.com/zitadel/zitadel/issues/11917 we want to
introduce error slugs so (API) clients can rely on stable,
machine-readable errors and act accordingly.
# How the Problems Are Solved
- Added a `NewSlug` helper function in the domain package.
- Added `ErrorDetails` to the `ZitadelError`
- Added an `zitadel.error.v2.ErrorDetail` proto message
- Updated the connectRPC error interceptor to map new slug based errors
to the new `ErrorDetail`
- Defined some common slugs and error functions like internal errors
- Defined (session) specific slugs used in the `DeleteSession` and
`CheckUser` functions and replaced old implementations
- Updated integration tests to check specific errors if the relation
database feature is enabled
- Updated doc and guideline to reflect the latest changes and decisions
- Updated DeleteSession endpoint API to list possible slugs
# Additional Changes
None
# Additional Context
- closes#11957
---------
Co-authored-by: Wim Van Laer <wim+github@zitadel.com>
# Which Problems Are Solved
As part of the naming consistency initiative, the term `Manager Roles`
is replaced by `Administrator Roles`
# How the Problems Are Solved
By replacing `Manager Roles` with `Administrator Roles` in API docs,
Console UI, and guides.
# Additional Changes
N/A
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/11293
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
# Which Problems Are Solved
REST paths for new APIs are unclear as they are not defined in the
API_DESIGN.
# How the Problems Are Solved
Add a part to the API_DESIGN, which can be removed at a later date when
migrating to RPC connect.
# Additional Changes
None
# Additional Context
None
# Which Problems Are Solved
As part of our efforts to simplify the structure and versions of our
APIs, were moving all existing v2beta endpoints to v2 and deprecate
them. They will be removed in Zitadel V5.
# How the Problems Are Solved
- This PR deprecates all settings v2beta service and endpoints.
- The comments and have been improved and, where not already done, moved
from swagger annotations to proto.
- `LoginSettings`:
- `AllowUsernamePassword` has been deprecated and a corresponding
`AllowLocalAuthentication` has been introduced
- `SECOND_FACTOR_TYPE_OTP` has been deprecated and a
`SECOND_FACTOR_TYPE_TOTP` has been introduced as enum alias
# Additional Changes
- cleanups of some unused structs
# Additional Context
- part of https://github.com/zitadel/zitadel/issues/10772
- requires backport to v4.x
The `Set` operation replaces the object, it must now allow partial
changes.
# Which Problems Are Solved
The definition of the `Set` operation was unclear.
# How the Problems Are Solved
Removed unclear description.
# Which Problems Are Solved
The commands for the resource based v2beta AuthorizationService API are
added.
Authorizations, previously knows as user grants, give a user in a
specific organization and project context roles.
The project can be owned or granted.
The given roles can be used to restrict access within the projects
applications.
The commands for the resource based v2beta InteralPermissionService API
are added.
Administrators, previously knows as memberships, give a user in a
specific organization and project context roles.
The project can be owned or granted.
The give roles give the user permissions to manage different resources
in Zitadel.
API definitions from https://github.com/zitadel/zitadel/issues/9165 are
implemented.
Contains endpoints for user metadata.
# How the Problems Are Solved
### New Methods
- CreateAuthorization
- UpdateAuthorization
- DeleteAuthorization
- ActivateAuthorization
- DeactivateAuthorization
- ListAuthorizations
- CreateAdministrator
- UpdateAdministrator
- DeleteAdministrator
- ListAdministrators
- SetUserMetadata to set metadata on a user
- DeleteUserMetadata to delete metadata on a user
- ListUserMetadata to query for metadata of a user
## Deprecated Methods
### v1.ManagementService
- GetUserGrantByID
- ListUserGrants
- AddUserGrant
- UpdateUserGrant
- DeactivateUserGrant
- ReactivateUserGrant
- RemoveUserGrant
- BulkRemoveUserGrant
### v1.AuthService
- ListMyUserGrants
- ListMyProjectPermissions
# Additional Changes
- Permission checks for metadata functionality on query and command side
- correct existence checks for resources, for example you can only be an
administrator on an existing project
- combined all member tables to singular query for the administrators
- add permission checks for command an query side functionality
- combined functions on command side where necessary for easier
maintainability
# Additional Context
Closes#9165
---------
Co-authored-by: Elio Bischof <elio@zitadel.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
This pull request addresses a significant gap in the user service v2
API, which currently lacks methods for managing machine users.
# How the Problems Are Solved
This PR adds new API endpoints to the user service v2 to manage machine
users including their secret, keys and personal access tokens.
Additionally, there's now a CreateUser and UpdateUser endpoints which
allow to create either a human or machine user and update them. The
existing `CreateHumanUser` endpoint has been deprecated along the
corresponding management service endpoints. For details check the
additional context section.
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/9349
## More details
- API changes: https://github.com/zitadel/zitadel/pull/9680
- Implementation: https://github.com/zitadel/zitadel/pull/9763
- Tests: https://github.com/zitadel/zitadel/pull/9771
## Follow-ups
- Metadata: support managing user metadata using resource API
https://github.com/zitadel/zitadel/pull/10005
- Machine token type: support managing the machine token type (migrate
to new enum with zero value unspecified?)
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Livio Spring <livio.a@gmail.com>
# Which Problems Are Solved
We have no standard way of deprecating API methods.
# How the Problems Are Solved
The API_DESIGN.md contains a section that describes how to deprecate
APIs.
Most importantly, deprecated APIs should link to replacement APIs for
good UX.
# Additional Context
- [x] Discussed with @stebenz during review of
https://github.com/zitadel/zitadel/pull/9743#discussion_r2081736144
- [ ] Inform backend engineers when this is merged.
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
# Which Problems Are Solved
There were some misunderstandings on how different points would be
needed to be applied into existing API definitions.
# How the Problems Are Solved
- Added structure to the API design
- Added points to context information in requests and responses
- Added examples to responses with context information
- Corrected available pagination messages
- Added pagination and filter examples
# Additional Changes
None
# Additional Context
None
# Which Problems Are Solved
The API guidelines were not completely accurate on how we want to check
permissions.
# How the Problems Are Solved
Made the description clearer and added examples.
# Additional Changes
Improved the error code example as initially intended in #9340
and added notes about the `limits` for listing resources.
# Additional Context
popped up in PR review of https://github.com/zitadel/zitadel/pull/9445
# Which Problems Are Solved
There were no guideline to how design future APIs and their endpoints.
The V3 documentation was to specific and targeted towards internal
stakeholders.
This PR is intended as base and kept to the minimum. If more details or
additional guideline or rules are needed, they will be added in the
future.
# How the Problems Are Solved
- Removed the V3 description and corresponding examples.
- Provided general guideline for the design of APIs, which includes the
structure, naming, versioning, error handling and more.
# Additional Changes
None
# Additional Context
closes#9184
---------
Co-authored-by: Maximilian <mpa@zitadel.com>
Co-authored-by: Silvan <27845747+adlerhurst@users.noreply.github.com>
Stefan BenzandGitHub
Livio SpringandGitHub
SilvanandGitHub
