Beta APIs Overview

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.

​

What are Beta APIs?

• Tested but evolving: The APIs are functional and tested, but the interface may change based on feedback and evolving requirements
• Subject to breaking changes: Unlike stable APIs, beta APIs may introduce breaking changes in minor or patch releases
• Transitional: Most beta APIs have corresponding stable v2 versions in development or already available

​

Stability Guarantees

​

What to Expect

• Functional: Beta APIs are production-ready and fully functional
• Documented: Comprehensive documentation is provided for all beta endpoints
• Supported: Issues and bugs are addressed through normal support channels
• Deprecation notices: Clear warnings are provided when endpoints will be removed

​

What Not to Expect

• API stability: Method signatures, request/response formats may change
• Long-term support: Beta APIs will be removed in future major versions
• Backward compatibility: Updates may require code changes in your application

​

Available Beta Services

• User Service: Manage user accounts, profiles, and authentication methods
• Organization Service: Handle organization management and domain verification
• Project Service: Manage projects, roles, and project grants
• App Service: Create and manage applications (OIDC, API, SAML)
• Session Service: Manage user sessions and authentication state
• OIDC Service: Handle OpenID Connect authentication flows
• Settings Service: Configure instance and organization settings
• Instance Service: Manage ZITADEL instances and domains
• Feature Service: Control feature flags at various levels
• Authorization Service: Manage user authorizations and grants
• Action Service: Configure actions, targets, and executions
• Web Key Service: Manage signing keys for OIDC tokens
• Telemetry Service: Report system metrics and resource counts

​

How to Access Beta Services

​

Initialize the Client

require 'zitadel_client'

# Configure the client
Zitadel::Client::Api.configure do |config|
  config.host = 'your-instance.zitadel.cloud'
  config.access_token = 'YOUR_ACCESS_TOKEN'
end

# Initialize a beta service
user_service = Zitadel::Client::Api::BetaUserServiceApi.new

​

Example Usage

# Create a request object
request = Zitadel::Client::BetaUserServiceAddHumanUserRequest.new(
  username: 'john.doe@example.com',
  profile: {
    first_name: 'John',
    last_name: 'Doe'
  },
  email: {
    email: 'john.doe@example.com',
    is_verified: false
  }
)

# Call the beta API
begin
  response = user_service.add_human_user(request)
  puts "User created: #{response.user_id}"
rescue Zitadel::Client::ApiError => e
  puts "Error: #{e.message}"
end

​

Migration Path to Stable APIs

​

Deprecation Timeline

1. Beta Release: API is available in beta namespace (v2beta)
2. Stable Release: Corresponding v2 API becomes generally available
3. Deprecation Notice: Beta API is marked deprecated (6-12 months notice)
4. Removal: Beta API is removed in next major version

​

Migration Strategy

​

1. Identify Stable Alternatives

# Beta (deprecated)
response = beta_user_service.add_human_user(request)

# Stable alternative
response = user_service_v2.add_human_user(request)

​

2. Test in Development

• Test the v2 endpoint with your use cases
• Verify response structure matches your expectations
• Check for any behavioral differences

​

3. Update Gradually

# Feature flag approach
def create_user(user_data)
  if use_v2_api?
    user_service_v2.add_human_user(user_data)
  else
    beta_user_service.add_human_user(user_data)
  end
end

​

4. Monitor for Issues

• Monitor error rates
• Validate response data
• Check performance metrics

​

Best Practices

​

When Using Beta APIs

1. Plan for Migration: Track which beta APIs you use and monitor for stable releases
2. Handle Errors Gracefully: Beta APIs may have more edge cases
3. Stay Updated: Regularly update the SDK to get latest improvements and fixes
4. Test Thoroughly: Beta APIs may have undocumented behavior
5. Read Deprecation Notices: Always check documentation for migration guidance

​

Error Handling

begin
  response = beta_service.method_call(request)
rescue Zitadel::Client::ApiError => e
  case e.code
  when 400
    # Bad request - check your parameters
  when 401
    # Unauthorized - check your access token
  when 404
    # Resource not found
  when 500
    # Server error - retry with backoff
  else
    # Handle other errors
  end
  
  # Log full error details
  Rails.logger.error "Zitadel API Error: #{e.message}"
  Rails.logger.error "Response body: #{e.response_body}"
end

​

Support and Resources

• SDK Repository: GitHub
• ZITADEL Documentation: Official Docs
• Community: Discord
• Issue Tracker: GitHub Issues

​

Version Information