Files
zitadel/proto/zitadel/authorization/v2/authorization_service.proto
T
Fabienne BühlerandGitHub 9a4530bf77 docs: Add note for updated terminology (#11802)
# Which Problems Are Solved

For existing customers it could be hard to understand the new aligned
terms we have defined, if they are already used to the "old term"

# How the Problems Are Solved

Adding notes at the top of docs pages to state clearliy new and old
terms.
2026-03-16 09:10:48 +00:00

332 lines
11 KiB
Protocol Buffer

syntax = "proto3";
package zitadel.authorization.v2;
import "protoc-gen-openapiv2/options/annotations.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/timestamp.proto";
import "validate/validate.proto";
import "google/api/annotations.proto";
import "zitadel/protoc_gen_zitadel/v2/options.proto";
import "zitadel/authorization/v2/authorization.proto";
import "zitadel/filter/v2/filter.proto";
option go_package = "github.com/zitadel/zitadel/pkg/grpc/authorization/v2;authorization";
// AuthorizationService provides methods to manage authorizations for users within your projects and applications.
//
// Note: We have streamlined our naming conventions to improve clarity. Authorization in this context refers to role assignments, not to OAuth authorization.
//
// For managing permissions and roles for Zitadel internal resources, like organizations, projects,
// users, etc., please use the InternalPermissionService.
service AuthorizationService {
// List Authorizations
//
// ListAuthorizations returns all authorizations matching the request and necessary permissions.
//
// Note: Authorization in this context refers to role assignments, not to OAuth authorization.
//
// Required permissions:
// - "user.grant.read"
// - no permissions required for listing own authorizations
rpc ListAuthorizations(ListAuthorizationsRequest) returns (ListAuthorizationsResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
}
// Create Authorization
//
// CreateAuthorization creates a new authorization for a user in an owned or granted project.
//
// Note: Authorization in this context refers to role assignments, not to OAuth authorization.
//
// Required permissions:
// - "user.grant.write"
rpc CreateAuthorization(CreateAuthorizationRequest) returns (CreateAuthorizationResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
}
// Update Authorization
//
// UpdateAuthorization updates the authorization.
//
// Note: Authorization in this context refers to role assignments, not to OAuth authorization.
//
// Note that any role keys previously granted to the user and not present in the request will be revoked.
//
// Required permissions:
// - "user.grant.write"
rpc UpdateAuthorization(UpdateAuthorizationRequest) returns (UpdateAuthorizationResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
}
// Delete Authorization
//
// DeleteAuthorization deletes the authorization.
//
// Note: Authorization in this context refers to role assignments, not to OAuth authorization.
//
// In case the authorization is not found, the request will return a successful response as
// the desired state is already achieved.
// You can check the deletion date in the response to verify if the authorization was deleted by the request.
//
// Required permissions:
// - "user.grant.delete"
rpc DeleteAuthorization(DeleteAuthorizationRequest) returns (DeleteAuthorizationResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
}
// Activate Authorization
//
// ActivateAuthorization activates an existing but inactive authorization.
//
// Note: Authorization in this context refers to role assignments, not to OAuth authorization.
//
// In case the authorization is already active, the request will return a successful response as
// the desired state is already achieved.
// You can check the change date in the response to verify if the authorization was activated by the request.
//
// Required permissions:
// - "user.grant.write"
rpc ActivateAuthorization(ActivateAuthorizationRequest) returns (ActivateAuthorizationResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
}
// Deactivate Authorization
//
// DeactivateAuthorization deactivates an existing and active authorization.
//
// Note: Authorization in this context refers to role assignments, not to OAuth authorization.
//
// In case the authorization is already inactive, the request will return a successful response as
// the desired state is already achieved.
// You can check the change date in the response to verify if the authorization was deactivated by the request.
//
// Required permissions:
// - "user.grant.write"
rpc DeactivateAuthorization(DeactivateAuthorizationRequest) returns (DeactivateAuthorizationResponse) {
option (zitadel.protoc_gen_zitadel.v2.options) = {
auth_option: {
permission: "authenticated"
}
};
}
}
message ListAuthorizationsRequest {
// Paginate through the results using a limit, offset and sorting.
optional zitadel.filter.v2.PaginationRequest pagination = 1;
// The field the result is sorted by. The default is the creation date.
// Beware that if you change this, your result pagination might be inconsistent.
AuthorizationFieldName sorting_column = 2 [
(validate.rules).enum = {defined_only: true}
];
// Define the criteria to query for.
repeated AuthorizationsSearchFilter filters = 3;
}
message ListAuthorizationsResponse {
// Contains the pagination information.
zitadel.filter.v2.PaginationResponse pagination = 1;
// Authorizations contains the list of authorizations matching the request.
repeated Authorization authorizations = 2;
}
message CreateAuthorizationRequest {
// UserID is the ID of the user who should be granted the authorization.
string user_id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
},
(google.api.field_behavior) = REQUIRED
];
// Project ID is the ID of the project the user should be authorized for.
string project_id = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
},
(google.api.field_behavior) = REQUIRED
];
// OrganizationID is the ID of the organization on which the authorization should be created.
// The organization must either own the project or have a grant for the project.
string organization_id = 3 [
(validate.rules).string = {min_len: 1, max_len: 200},
(google.api.field_behavior) = REQUIRED,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1,
max_length: 200;
example: "\"163840776835432345\"";
}
];
// RoleKeys are the keys of the roles the user should be granted.
repeated string role_keys = 4 [
(validate.rules).repeated = {
unique: true
items: {
string: {
min_len: 1
max_len: 200
}
}
},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "[\"user\",\"admin\"]";
}
];
}
message CreateAuthorizationResponse {
// ID is the unique identifier of the newly created authorization.
string id = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"69629012906488334\"";
}
];
// CreationDate is the timestamp when the authorization was created.
google.protobuf.Timestamp creation_date = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2025-01-23T10:34:18.051Z\"";
}
];
}
message UpdateAuthorizationRequest {
// ID is the unique identifier of the authorization.
string id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
}
];
// RoleKeys are the keys of the roles the user should be granted.
// Note that any role keys previously granted to the user and not present in the list will be revoked.
repeated string role_keys = 2 [
(validate.rules).repeated = {
unique: true
items: {
string: {
min_len: 1
max_len: 200
}
}
},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "[\"user\",\"admin\"]";
}
];
}
message UpdateAuthorizationResponse {
// ChangeDate is the timestamp when the authorization was last updated.
google.protobuf.Timestamp change_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}
message DeleteAuthorizationRequest {
// ID is the unique identifier of the authorization that should be deleted.
string id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
},
(google.api.field_behavior) = REQUIRED
];
}
message DeleteAuthorizationResponse {
// DeletionDate is the timestamp when the authorization was deleted.
google.protobuf.Timestamp deletion_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}
message ActivateAuthorizationRequest {
// ID is the unique identifier of the authorization that should be activated.
string id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
},
(google.api.field_behavior) = REQUIRED
];
}
message ActivateAuthorizationResponse {
// ChangeDate is the last timestamp when the authorization was changed / activated.
google.protobuf.Timestamp change_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}
message DeactivateAuthorizationRequest {
// ID is the unique identifier of the authorization that should be deactivated.
string id = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
min_length: 1;
max_length: 200;
example: "\"163840776835432345\"";
},
(google.api.field_behavior) = REQUIRED
];
}
message DeactivateAuthorizationResponse {
// ChangeDate is the last timestamp when the authorization was changed / deactivated.
google.protobuf.Timestamp change_date = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2024-12-18T07:50:47.492Z\"";
}
];
}