Skip to main content
Deprecated: Please move to the corresponding endpoints under Project Service v2. This service will be removed in the next major version of ZITADEL.

​
Overview

The BetaProjectServiceApi provides methods for managing projects, project roles, and project grants in ZITADEL.

​
Initialization

require 'zitadel/client'

client = Zitadel::Client::ApiClient.new
client.config.access_token = 'your_access_token'

project_service = Zitadel::Client::Api::BetaProjectServiceApi.new(client)

​
Key Methods

​
Project Management

​
beta_project_service_create_project_request
object
required
Request containing project details
request = Zitadel::Client::Models::BetaProjectServiceCreateProjectRequest.new(
  name: 'My Application',
  project_role_assertion: true,
  project_role_check: true
)

response = project_service.create_project(request)
puts "Project ID: #{response.id}"
Required Permission: project.create
request = Zitadel::Client::Models::BetaProjectServiceGetProjectRequest.new(
  project_id: '123456789'
)

response = project_service.get_project(request)
puts "Project: #{response.project.name}"
Required Permission: project.read
​
beta_project_service_list_projects_request
object
required
Request with filters and pagination
request = Zitadel::Client::Models::BetaProjectServiceListProjectsRequest.new(
  limit: 50
)

response = project_service.list_projects(request)
response.result.each do |project|
  puts "Project: #{project.name}"
end
Required Permission: project.read
request = Zitadel::Client::Models::BetaProjectServiceUpdateProjectRequest.new(
  project_id: '123456789',
  name: 'Updated Application Name'
)

project_service.update_project(request)
Required Permission: project.write
Deletes the project. Returns success even if not found.
request = Zitadel::Client::Models::BetaProjectServiceDeleteProjectRequest.new(
  project_id: '123456789'
)

project_service.delete_project(request)
Required Permission: project.delete

​
Project Lifecycle

Sets project state to active. Returns success if already active.
request = Zitadel::Client::Models::BetaProjectServiceActivateProjectRequest.new(
  project_id: '123456789'
)

project_service.activate_project(request)
Required Permission: project.write
Sets project state to deactivated. Applications cannot login.
request = Zitadel::Client::Models::BetaProjectServiceDeactivateProjectRequest.new(
  project_id: '123456789'
)

project_service.deactivate_project(request)
Required Permission: project.write

​
Role Management

Adds a new role to the project. Key must be unique within the project.
request = Zitadel::Client::Models::BetaProjectServiceAddProjectRoleRequest.new(
  project_id: '123456789',
  role_key: 'admin',
  display_name: 'Administrator',
  group: 'Management'
)

project_service.add_project_role(request)
Required Permission: project.role.write
Returns all roles matching the search query.
request = Zitadel::Client::Models::BetaProjectServiceListProjectRolesRequest.new(
  project_id: '123456789'
)

response = project_service.list_project_roles(request)
response.result.each do |role|
  puts "Role: #{role.role_key} - #{role.display_name}"
end
Required Permission: project.role.read
Changes role properties. Key cannot be changed.
request = Zitadel::Client::Models::BetaProjectServiceUpdateProjectRoleRequest.new(
  project_id: '123456789',
  role_key: 'admin',
  display_name: 'Super Administrator'
)

project_service.update_project_role(request)
Required Permission: project.role.write
Removes the role from project and all dependent resources (grants).
request = Zitadel::Client::Models::BetaProjectServiceRemoveProjectRoleRequest.new(
  project_id: '123456789',
  role_key: 'admin'
)

project_service.remove_project_role(request)
Required Permission: project.role.write

​
Project Grants

Grants project access to another organization.
request = Zitadel::Client::Models::BetaProjectServiceCreateProjectGrantRequest.new(
  project_id: '123456789',
  granted_org_id: '987654321',
  role_keys: ['viewer', 'editor']
)

response = project_service.create_project_grant(request)
puts "Grant ID: #{response.grant_id}"
Required Permission: project.grant.create
Returns all project grants.
request = Zitadel::Client::Models::BetaProjectServiceListProjectGrantsRequest.new(
  project_id: '123456789'
)

response = project_service.list_project_grants(request)
response.result.each do |grant|
  puts "Grant to: #{grant.granted_org_id}"
end
Required Permission: project.grant.write
Changes which roles are granted to the organization.
request = Zitadel::Client::Models::BetaProjectServiceUpdateProjectGrantRequest.new(
  project_id: '123456789',
  grant_id: '555666777',
  role_keys: ['viewer'] # Updated role list
)

project_service.update_project_grant(request)
Required Permission: project.grant.write
Sets grant state to activated.
request = Zitadel::Client::Models::BetaProjectServiceActivateProjectGrantRequest.new(
  project_id: '123456789',
  grant_id: '555666777'
)

project_service.activate_project_grant(request)
Required Permission: project.grant.write
Sets grant state to deactivated. Applications cannot login.
request = Zitadel::Client::Models::BetaProjectServiceDeactivateProjectGrantRequest.new(
  project_id: '123456789',
  grant_id: '555666777'
)

project_service.deactivate_project_grant(request)
Required Permission: project.grant.write
Deletes the grant and all associated user grants. Returns success if not found.
request = Zitadel::Client::Models::BetaProjectServiceDeleteProjectGrantRequest.new(
  project_id: '123456789',
  grant_id: '555666777'
)

project_service.delete_project_grant(request)
Required Permission: project.grant.delete

​
Required Permissions

  • project.read - Read project information
  • project.write - Modify projects
  • project.create - Create new projects
  • project.delete - Delete projects
  • project.role.read - Read project roles
  • project.role.write - Modify project roles
  • project.grant.read - Read project grants
  • project.grant.write - Modify project grants
  • project.grant.create - Create project grants
  • project.grant.delete - Delete project grants

​
Migration Guide

To migrate to Project Service v2:
  1. Replace BetaProjectServiceApi with ProjectServiceV2Api
  2. Update request/response models
  3. Review grant management changes
  4. Test role assignments

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us