The Project Service provides methods to create and manage projects, which are used to group applications, roles, and authorizations.
Overview
The ProjectServiceApi class provides methods for:
- Creating and managing projects
- Managing project roles
- Managing project grants for cross-organization access
- Project state management
- Listing and searching projects
Initialization
require 'zitadel/client'
api_client = Zitadel::Client::ApiClient.new
api_client.config.access_token = 'YOUR_ACCESS_TOKEN'
project_service = Zitadel::Client::Api::ProjectServiceApi.new(api_client)
Project Management
create_project
Create a new project. Every project belongs to exactly one organization.
request = Zitadel::Client::ProjectServiceCreateProjectRequest.new(
name: 'My Application',
project_role_assertion: true,
project_role_check: true
)
response = project_service.create_project(request)
puts "Project ID: #{response.project_id}"
Whether project roles should be asserted in tokens
Whether project role checks should be enforced
The unique identifier of the created project
get_project
Retrieve a project by ID.
request = Zitadel::Client::ProjectServiceGetProjectRequest.new(
project_id: 'project_123'
)
response = project_service.get_project(request)
puts "Project: #{response.project.name}"
list_projects
List projects with filtering and pagination.
request = Zitadel::Client::ProjectServiceListProjectsRequest.new(
query: Zitadel::Client::ProjectServicePaginationRequest.new(
limit: 50,
offset: 0
),
queries: [
Zitadel::Client::ProjectServiceProjectSearchFilter.new(
name_filter: Zitadel::Client::ProjectServiceProjectNameFilter.new(
name: 'My',
method: 'TEXT_FILTER_METHOD_CONTAINS'
)
)
]
)
response = project_service.list_projects(request)
response.result.each do |project|
puts "Project: #{project.name}"
end
update_project
Update project details.
request = Zitadel::Client::ProjectServiceUpdateProjectRequest.new(
project_id: 'project_123',
name: 'My Updated Application'
)
response = project_service.update_project(request)
activate_project
Activate a project. No error if already active.
request = Zitadel::Client::ProjectServiceActivateProjectRequest.new(
project_id: 'project_123'
)
response = project_service.activate_project(request)
deactivate_project
Deactivate a project.
request = Zitadel::Client::ProjectServiceDeactivateProjectRequest.new(
project_id: 'project_123'
)
response = project_service.deactivate_project(request)
delete_project
Permanently delete a project.
request = Zitadel::Client::ProjectServiceDeleteProjectRequest.new(
project_id: 'project_123'
)
response = project_service.delete_project(request)
Project Roles
add_project_role
Add a new role to a project. The key must be unique within the project.
request = Zitadel::Client::ProjectServiceAddProjectRoleRequest.new(
project_id: 'project_123',
role_key: 'admin',
display_name: 'Administrator',
group: 'Management'
)
response = project_service.add_project_role(request)
Display name for the role
Optional group for organizing roles
list_project_roles
List all roles in a project.
request = Zitadel::Client::ProjectServiceListProjectRolesRequest.new(
project_id: 'project_123',
query: Zitadel::Client::ProjectServicePaginationRequest.new(
limit: 100
)
)
response = project_service.list_project_roles(request)
response.result.each do |role|
puts "Role: #{role.key} - #{role.display_name}"
end
update_project_role
Update an existing project role.
request = Zitadel::Client::ProjectServiceUpdateProjectRoleRequest.new(
project_id: 'project_123',
role_key: 'admin',
display_name: 'Super Administrator'
)
response = project_service.update_project_role(request)
remove_project_role
Remove a role from a project.
request = Zitadel::Client::ProjectServiceRemoveProjectRoleRequest.new(
project_id: 'project_123',
role_key: 'admin'
)
response = project_service.remove_project_role(request)
Project Grants
Project grants allow other organizations to manage their own authorizations for your project.
create_project_grant
Grant another organization access to manage authorizations for specific roles in your project.
request = Zitadel::Client::ProjectServiceCreateProjectGrantRequest.new(
project_id: 'project_123',
granted_org_id: 'org_456',
role_keys: ['reader', 'editor']
)
response = project_service.create_project_grant(request)
puts "Grant ID: #{response.grant_id}"
The project ID to grant access to
The organization receiving the grant
List of role keys to include in the grant
list_project_grants
List all grants for a project.
request = Zitadel::Client::ProjectServiceListProjectGrantsRequest.new(
project_id: 'project_123',
query: Zitadel::Client::ProjectServicePaginationRequest.new(
limit: 50
)
)
response = project_service.list_project_grants(request)
response.result.each do |grant|
puts "Grant to org: #{grant.granted_org_id}"
end
update_project_grant
Update the roles included in a project grant.
request = Zitadel::Client::ProjectServiceUpdateProjectGrantRequest.new(
project_id: 'project_123',
grant_id: 'grant_789',
role_keys: ['reader', 'editor', 'admin']
)
response = project_service.update_project_grant(request)
activate_project_grant
Activate a project grant.
request = Zitadel::Client::ProjectServiceActivateProjectGrantRequest.new(
project_id: 'project_123',
grant_id: 'grant_789'
)
response = project_service.activate_project_grant(request)
deactivate_project_grant
Deactivate a project grant.
request = Zitadel::Client::ProjectServiceDeactivateProjectGrantRequest.new(
project_id: 'project_123',
grant_id: 'grant_789'
)
response = project_service.deactivate_project_grant(request)
delete_project_grant
Permanently delete a project grant.
request = Zitadel::Client::ProjectServiceDeleteProjectGrantRequest.new(
project_id: 'project_123',
grant_id: 'grant_789'
)
response = project_service.delete_project_grant(request)
Complete Example
require 'zitadel/client'
api_client = Zitadel::Client::ApiClient.new
api_client.config.access_token = ENV['ZITADEL_ACCESS_TOKEN']
project_service = Zitadel::Client::Api::ProjectServiceApi.new(api_client)
begin
# Create project
create_request = Zitadel::Client::ProjectServiceCreateProjectRequest.new(
name: 'Customer Portal',
project_role_assertion: true,
project_role_check: true
)
project_response = project_service.create_project(create_request)
project_id = project_response.project_id
puts "Created project: #{project_id}"
# Add roles
['admin', 'editor', 'reader'].each do |role|
role_request = Zitadel::Client::ProjectServiceAddProjectRoleRequest.new(
project_id: project_id,
role_key: role,
display_name: role.capitalize
)
project_service.add_project_role(role_request)
puts "Added role: #{role}"
end
# Create project grant
grant_request = Zitadel::Client::ProjectServiceCreateProjectGrantRequest.new(
project_id: project_id,
granted_org_id: 'partner_org_id',
role_keys: ['reader']
)
grant_response = project_service.create_project_grant(grant_request)
puts "Created grant: #{grant_response.grant_id}"
rescue Zitadel::Client::ApiError => e
puts "Error: #{e.message}"
end
See Also
