Skip to main content

​
Overview

The AuthorizationServiceApi provides methods for managing user authorizations (also known as user grants) in Zitadel. Authorizations define which roles a user has in a project or project grant.

​
Initialize the API

require 'zitadel/client'

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

auth_api = Zitadel::Client::Api::AuthorizationServiceApi.new(client)

​
Authorization Management

Create a new authorization for a user in an owned or granted project.Required permission: user.grant.write
request = Zitadel::Client::AuthorizationServiceCreateAuthorizationRequest.new(
  user_id: 'user_123',
  project: {
    project_id: 'project_456',
    role_keys: ['admin', 'editor']
  }
)

response = auth_api.create_authorization(request)
puts "Authorization ID: #{response.id}"
​
user_id
string
required
The ID of the user to grant authorization to
​
project_id
string
required
The ID of the project
​
role_keys
array
required
Array of role keys to grant to the user
Update the roles of an existing authorization.Required permission: user.grant.write
request = Zitadel::Client::AuthorizationServiceUpdateAuthorizationRequest.new(
  authorization_id: 'auth_123',
  role_keys: ['admin', 'editor', 'viewer']
)

response = auth_api.update_authorization(request)
Delete an authorization.Required permission: user.grant.delete
request = Zitadel::Client::AuthorizationServiceDeleteAuthorizationRequest.new(
  authorization_id: 'auth_123'
)

response = auth_api.delete_authorization(request)
Search for authorizations matching the given query.Required permission: user.grant.read
request = Zitadel::Client::AuthorizationServiceListAuthorizationsRequest.new(
  queries: [{
    user_id_query: {
      user_id: 'user_123'
    }
  }]
)

response = auth_api.list_authorizations(request)
response.result.each do |authorization|
  puts "Project: #{authorization.project_id}"
  puts "Roles: #{authorization.role_keys.join(', ')}"
end

​
Authorization State Management

Activate an existing but inactive authorization.Required permission: user.grant.write
request = Zitadel::Client::AuthorizationServiceActivateAuthorizationRequest.new(
  authorization_id: 'auth_123'
)

response = auth_api.activate_authorization(request)
Deactivate an existing and active authorization.Required permission: user.grant.write
request = Zitadel::Client::AuthorizationServiceDeactivateAuthorizationRequest.new(
  authorization_id: 'auth_123'
)

response = auth_api.deactivate_authorization(request)

​
Authorization Types

​
Project Authorization

Grants roles for a project owned by the current organization: 
project: {
  project_id: 'project_123',
  role_keys: ['admin', 'user']
}

​
Project Grant Authorization

Grants roles for a project that has been granted to the organization: 
project_grant: {
  project_id: 'project_123',
  project_grant_id: 'grant_456',
  role_keys: ['user', 'viewer']
}

​
Example: Grant User Access to Project

# Create authorization for a user
request = Zitadel::Client::AuthorizationServiceCreateAuthorizationRequest.new(
  user_id: 'user_123',
  project: {
    project_id: 'project_456',
    role_keys: ['user', 'viewer']
  }
)

response = auth_api.create_authorization(request)
authorization_id = response.id

puts "Granted user access to project"
puts "Authorization ID: #{authorization_id}"

​
Example: Update User Roles

# Add more roles to an existing authorization
request = Zitadel::Client::AuthorizationServiceUpdateAuthorizationRequest.new(
  authorization_id: 'auth_123',
  role_keys: ['user', 'viewer', 'editor', 'admin'] # Updated roles
)

response = auth_api.update_authorization(request)
puts "Updated user roles"

​
Example: List User’s Authorizations

# Get all authorizations for a specific user
request = Zitadel::Client::AuthorizationServiceListAuthorizationsRequest.new(
  queries: [{
    user_id_query: {
      user_id: 'user_123'
    }
  }]
)

response = auth_api.list_authorizations(request)

puts "User has #{response.result.length} authorization(s):"

response.result.each do |auth|
  puts ""
  puts "Authorization ID: #{auth.id}"
  puts "Project ID: #{auth.project_id}"
  puts "State: #{auth.state}"
  puts "Roles: #{auth.role_keys.join(', ')}"
  puts "Created: #{auth.details.creation_date}"
end

​
Example: Temporary Access (Activate/Deactivate)

# Temporarily disable user access
deactivate_request = Zitadel::Client::AuthorizationServiceDeactivateAuthorizationRequest.new(
  authorization_id: 'auth_123'
)

auth_api.deactivate_authorization(deactivate_request)
puts "User access temporarily disabled"

# Later, re-enable access
activate_request = Zitadel::Client::AuthorizationServiceActivateAuthorizationRequest.new(
  authorization_id: 'auth_123'
)

auth_api.activate_authorization(activate_request)
puts "User access re-enabled"

​
Example: Search Authorizations by Project

# Find all users who have access to a specific project
request = Zitadel::Client::AuthorizationServiceListAuthorizationsRequest.new(
  queries: [{
    project_id_query: {
      project_id: 'project_456'
    }
  }]
)

response = auth_api.list_authorizations(request)

puts "#{response.result.length} user(s) have access to project:"

response.result.each do |auth|
  puts "User: #{auth.user_id}"
  puts "  Roles: #{auth.role_keys.join(', ')}"
  puts "  State: #{auth.state}"
end

​
Example: Bulk Authorization Management

# Grant same roles to multiple users
users = ['user_1', 'user_2', 'user_3']
project_id = 'project_456'
roles = ['user', 'viewer']

users.each do |user_id|
  request = Zitadel::Client::AuthorizationServiceCreateAuthorizationRequest.new(
    user_id: user_id,
    project: {
      project_id: project_id,
      role_keys: roles
    }
  )
  
  begin
    response = auth_api.create_authorization(request)
    puts "Granted access to #{user_id}: #{response.id}"
  rescue => e
    puts "Failed to grant access to #{user_id}: #{e.message}"
  end
end

​
Authorization Query Filters

You can filter authorizations using various queries:

​
By User ID

user_id_query: {
  user_id: 'user_123'
}

​
By Project ID

project_id_query: {
  project_id: 'project_456'
}

​
By Organization ID

organization_id_query: {
  organization_id: 'org_789'
}

​
By State

state_query: {
  state: 'AUTHORIZATION_STATE_ACTIVE'
}

​
Authorization States

  • ACTIVE: The authorization is active and the user can use the granted roles
  • INACTIVE: The authorization exists but is temporarily disabled

​
Best Practices

  1. Principle of Least Privilege: Only grant the minimum roles required
  2. Regular Audits: Periodically review and clean up unused authorizations
  3. Use Groups: Consider using groups for managing permissions at scale
  4. Document Roles: Maintain clear documentation of what each role allows
  5. Temporary Access: Use activate/deactivate for temporary access instead of delete/create
  6. Error Handling: Always handle cases where authorizations may already exist or not be found
  7. Pagination: Use pagination when listing authorizations for large datasets

​
Integration with Projects

Authorizations are tightly coupled with projects and roles: 
# First, ensure the project and roles exist
project_api = Zitadel::Client::Api::ProjectServiceApi.new(client)

# List available roles in the project
roles_request = Zitadel::Client::ProjectServiceListProjectRolesRequest.new(
  project_id: 'project_456'
)

roles_response = project_api.list_project_roles(roles_request)
available_roles = roles_response.result.map(&:key)

puts "Available roles: #{available_roles.join(', ')}"

# Then create authorization with valid roles
auth_request = Zitadel::Client::AuthorizationServiceCreateAuthorizationRequest.new(
  user_id: 'user_123',
  project: {
    project_id: 'project_456',
    role_keys: available_roles.take(2) # Grant first 2 roles
  }
)

auth_api.create_authorization(auth_request)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us