Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zitadel/client-ruby/llms.txt
Use this file to discover all available pages before exploring further.
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
