BetaAuthorizationServiceApi

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

Overview

The BetaAuthorizationServiceApi provides methods for managing user authorizations (grants) to projects and their roles.

Initialization

require 'zitadel/client'

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

auth_service = Zitadel::Client::Api::BetaAuthorizationServiceApi.new(client)

Key Methods

Authorization Management

create_authorization - Grant user access to project

beta_authorization_service_create_authorization_request

object

required

Authorization creation request

Show properties

user_id

string

required

ID of the user to authorize

project_id

string

required

Project to grant access to

project_grant_id

string

Specific project grant (optional)

role_keys

array

required

List of role keys to grant

request = Zitadel::Client::Models::BetaAuthorizationServiceCreateAuthorizationRequest.new(
  user_id: '123456789',
  project_id: '987654321',
  role_keys: ['admin', 'editor']
)

response = auth_service.create_authorization(request)
puts "Authorization ID: #{response.authorization_id}"

Required Permission: user.grant.writeReturns: BetaAuthorizationServiceCreateAuthorizationResponse

list_authorizations - List user authorizations

beta_authorization_service_list_authorizations_request

object

required

Search and filter parameters

Show properties

queries

array

Filter by user, project, or organization

limit

integer

Results per page

# List authorizations for a specific user
request = Zitadel::Client::Models::BetaAuthorizationServiceListAuthorizationsRequest.new(
  queries: [
    {
      user_id_query: {
        user_id: '123456789'
      }
    }
  ],
  limit: 50
)

response = auth_service.list_authorizations(request)

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

Required Permission:

user.grant.read for others’ authorizations
No permission required for own authorizations

Returns: BetaAuthorizationServiceListAuthorizationsResponse

update_authorization - Update authorization roles

Changes which roles are granted to the user.

Any role keys not included in the request will be revoked.

request = Zitadel::Client::Models::BetaAuthorizationServiceUpdateAuthorizationRequest.new(
  authorization_id: '111222333',
  role_keys: ['viewer'] # Previous roles will be replaced
)

auth_service.update_authorization(request)

Required Permission: user.grant.writeReturns: BetaAuthorizationServiceUpdateAuthorizationResponse

delete_authorization - Revoke authorization

Deletes the authorization, revoking user’s access to the project.

request = Zitadel::Client::Models::BetaAuthorizationServiceDeleteAuthorizationRequest.new(
  authorization_id: '111222333'
)

response = auth_service.delete_authorization(request)
puts "Deleted at: #{response.details.change_date}"

Returns success even if authorization is not found (idempotent).

Required Permission: user.grant.deleteReturns: BetaAuthorizationServiceDeleteAuthorizationResponse

Authorization State Management

activate_authorization - Activate authorization

Sets authorization state to active. Returns success if already active.

request = Zitadel::Client::Models::BetaAuthorizationServiceActivateAuthorizationRequest.new(
  authorization_id: '111222333'
)

auth_service.activate_authorization(request)

Required Permission: user.grant.writeReturns: BetaAuthorizationServiceActivateAuthorizationResponse

deactivate_authorization - Deactivate authorization

Sets authorization state to inactive. User loses access temporarily.

request = Zitadel::Client::Models::BetaAuthorizationServiceDeactivateAuthorizationRequest.new(
  authorization_id: '111222333'
)

auth_service.deactivate_authorization(request)

Required Permission: user.grant.writeReturns: BetaAuthorizationServiceDeactivateAuthorizationResponse

Authorization Queries

Filter authorizations by different criteria:

By User ID

queries: [
  {
    user_id_query: {
      user_id: '123456789'
    }
  }
]

By Project ID

queries: [
  {
    project_id_query: {
      project_id: '987654321'
    }
  }
]

By Organization ID

queries: [
  {
    organization_id_query: {
      organization_id: '555666777'
    }
  }
]

By Project Grant ID

queries: [
  {
    project_grant_id_query: {
      project_grant_id: '444555666'
    }
  }
]

Multiple Filters

# Find authorizations for specific user in specific project
queries: [
  {
    user_id_query: { user_id: '123456789' }
  },
  {
    project_id_query: { project_id: '987654321' }
  }
]

Use Cases

Grant User Access to Application

def grant_user_access(user_id, project_id, roles)
  request = Zitadel::Client::Models::BetaAuthorizationServiceCreateAuthorizationRequest.new(
    user_id: user_id,
    project_id: project_id,
    role_keys: roles
  )
  
  response = auth_service.create_authorization(request)
  
  puts "User #{user_id} granted roles: #{roles.join(', ')}"
  response.authorization_id
end

# Usage
grant_user_access('user_123', 'project_456', ['admin', 'editor'])

Check User Project Access

def user_has_project_access?(user_id, project_id)
  request = Zitadel::Client::Models::BetaAuthorizationServiceListAuthorizationsRequest.new(
    queries: [
      { user_id_query: { user_id: user_id } },
      { project_id_query: { project_id: project_id } }
    ]
  )
  
  response = auth_service.list_authorizations(request)
  
  # Check if any active authorization exists
  response.result.any? { |auth| auth.state == 'ACTIVE' }
rescue
  false
end

List User’s All Project Access

def list_user_projects(user_id)
  request = Zitadel::Client::Models::BetaAuthorizationServiceListAuthorizationsRequest.new(
    queries: [
      { user_id_query: { user_id: user_id } }
    ]
  )
  
  response = auth_service.list_authorizations(request)
  
  projects = response.result.map do |auth|
    {
      project_id: auth.project_id,
      roles: auth.role_keys,
      state: auth.state,
      organization_id: auth.organization_id
    }
  end
  
  projects
end

Promote User Role

def promote_user(authorization_id, new_roles)
  # Update authorization with new roles
  request = Zitadel::Client::Models::BetaAuthorizationServiceUpdateAuthorizationRequest.new(
    authorization_id: authorization_id,
    role_keys: new_roles
  )
  
  auth_service.update_authorization(request)
  puts "User promoted to roles: #{new_roles.join(', ')}"
end

# Usage: Promote viewer to editor
promote_user('auth_123', ['editor', 'viewer'])

Temporarily Suspend User Access

def suspend_user_access(user_id, project_id)
  # Find authorization
  request = Zitadel::Client::Models::BetaAuthorizationServiceListAuthorizationsRequest.new(
    queries: [
      { user_id_query: { user_id: user_id } },
      { project_id_query: { project_id: project_id } }
    ]
  )
  
  response = auth_service.list_authorizations(request)
  
  # Deactivate each authorization
  response.result.each do |auth|
    deactivate_req = Zitadel::Client::Models::BetaAuthorizationServiceDeactivateAuthorizationRequest.new(
      authorization_id: auth.authorization_id
    )
    
    auth_service.deactivate_authorization(deactivate_req)
    puts "Suspended authorization: #{auth.authorization_id}"
  end
end

Audit User Permissions

def audit_user_permissions(user_id)
  request = Zitadel::Client::Models::BetaAuthorizationServiceListAuthorizationsRequest.new(
    queries: [
      { user_id_query: { user_id: user_id } }
    ]
  )
  
  response = auth_service.list_authorizations(request)
  
  report = {
    user_id: user_id,
    total_authorizations: response.details.total_result,
    active_count: 0,
    inactive_count: 0,
    projects: []
  }
  
  response.result.each do |auth|
    if auth.state == 'ACTIVE'
      report[:active_count] += 1
    else
      report[:inactive_count] += 1
    end
    
    report[:projects] << {
      project_id: auth.project_id,
      organization_id: auth.organization_id,
      roles: auth.role_keys,
      state: auth.state,
      created: auth.details.creation_date
    }
  end
  
  report
end

Bulk Grant Access

def bulk_grant_access(user_ids, project_id, roles)
  results = []
  
  user_ids.each do |user_id|
    begin
      request = Zitadel::Client::Models::BetaAuthorizationServiceCreateAuthorizationRequest.new(
        user_id: user_id,
        project_id: project_id,
        role_keys: roles
      )
      
      response = auth_service.create_authorization(request)
      results << { user_id: user_id, success: true, authorization_id: response.authorization_id }
    rescue => e
      results << { user_id: user_id, success: false, error: e.message }
    end
  end
  
  results
end

# Usage
users = ['user_1', 'user_2', 'user_3']
results = bulk_grant_access(users, 'project_456', ['viewer'])

results.each do |result|
  if result[:success]
    puts "✓ Granted access to #{result[:user_id]}"
  else
    puts "✗ Failed for #{result[:user_id]}: #{result[:error]}"
  end
end

Authorization States

STATE_ACTIVE - User has active access
STATE_INACTIVE - Access temporarily suspended

Required Permissions

user.grant.read - Read authorizations
user.grant.write - Create/modify authorizations
user.grant.delete - Delete authorizations

Users can always list their own authorizations without permissions.

Migration Guide

To migrate to Authorization Service v2:

Replace BetaAuthorizationServiceApi with AuthorizationServiceV2Api
Update request/response models
Review authorization query structure
Test permission checks

Client

Stable APIs

Beta APIs

Models

Overview

Initialization

Key Methods

Authorization Management

Authorization State Management

Authorization Queries

By User ID

By Project ID

By Organization ID

By Project Grant ID

Multiple Filters

Use Cases

Grant User Access to Application

Check User Project Access

List User’s All Project Access

Promote User Role

Temporarily Suspend User Access

Audit User Permissions

Bulk Grant Access

Authorization States

Required Permissions

Migration Guide

See Also

Build docs developers (and LLMs) love

Client

Stable APIs

Beta APIs

Models

​Overview

​Initialization

​Key Methods

​Authorization Management

​Authorization State Management

​Authorization Queries

​By User ID

​By Project ID

​By Organization ID

​By Project Grant ID

​Multiple Filters

​Use Cases

​Grant User Access to Application

​Check User Project Access

​List User’s All Project Access

​Promote User Role

​Temporarily Suspend User Access

​Audit User Permissions

​Bulk Grant Access

​Authorization States

​Required Permissions

​Migration Guide

​See Also

Build docs developers (and LLMs) love

Overview

Initialization

Key Methods

Authorization Management

Authorization State Management

Authorization Queries

By User ID

By Project ID

By Organization ID

By Project Grant ID

Multiple Filters

Use Cases

Grant User Access to Application

Check User Project Access

List User’s All Project Access

Promote User Role

Temporarily Suspend User Access

Audit User Permissions

Bulk Grant Access

Authorization States

Required Permissions

Migration Guide

See Also