Deprecated: Please move to the corresponding endpoints under Session Service v2. This service will be removed in the next major version of ZITADEL.
Overview
The BetaSessionServiceApi provides methods for creating, managing, and terminating user sessions.
Initialization
require 'zitadel/client'
client = Zitadel::Client::ApiClient.new
client.config.access_token = 'your_access_token'
session_service = Zitadel::Client::Api::BetaSessionServiceApi.new(client)
Key Methods
Session Creation
create_session - Create a new session
beta_session_service_create_session_request
Session creation parameters
Authentication checks to perform
Additional session metadata
Session lifetime duration
request = Zitadel::Client::Models::BetaSessionServiceCreateSessionRequest.new(
checks: {
user: {
login_name: '[email protected]'
},
password: {
password: 'secure_password'
}
},
metadata: {
user_agent: 'Mozilla/5.0...',
ip_address: '192.168.1.1'
}
)
response = session_service.create_session(request)
puts "Session ID: #{response.session_id}"
puts "Session Token: #{response.session_token}"
BetaSessionServiceCreateSessionResponseSession Retrieval
get_session - Get session details
beta_session_service_get_session_request
Request with session identifier
The session ID to retrieve
Alternative: session token
request = Zitadel::Client::Models::BetaSessionServiceGetSessionRequest.new(
session_id: 'session_123456'
)
response = session_service.get_session(request)
puts "User ID: #{response.session.user_id}"
puts "Created: #{response.session.creation_date}"
puts "Expiration: #{response.session.expiration_date}"
BetaSessionServiceGetSessionResponselist_sessions - Search for sessions
beta_session_service_list_sessions_request
Search and pagination parameters
Filter criteria (by user, creation time, etc.)
Number of results per page
request = Zitadel::Client::Models::BetaSessionServiceListSessionsRequest.new(
queries: [
{
user_id_query: {
user_id: '123456789'
}
}
],
limit: 50
)
response = session_service.list_sessions(request)
response.result.each do |session|
puts "Session: #{session.session_id} (created: #{session.creation_date})"
end
BetaSessionServiceListSessionsResponseSession Updates
set_session - Update session
beta_session_service_set_session_request
Session update parameters
Additional authentication checks
request = Zitadel::Client::Models::BetaSessionServiceSetSessionRequest.new(
session_id: 'session_123456',
checks: {
totp: {
code: '123456'
}
},
metadata: {
mfa_verified: true
}
)
response = session_service.set_session(request)
puts "Session updated: #{response.session_id}"
BetaSessionServiceSetSessionResponseSession Termination
delete_session - Terminate a session
beta_session_service_delete_session_request
Session identifier to terminate
The session ID to terminate
Alternative: session token
request = Zitadel::Client::Models::BetaSessionServiceDeleteSessionRequest.new(
session_id: 'session_123456'
)
response = session_service.delete_session(request)
puts "Session terminated at: #{response.details.change_date}"
BetaSessionServiceDeleteSessionResponseSession Checks
When creating or updating sessions, you can perform various authentication checks:
User Check
Password Check
checks: {
password: {
password: 'user_password'
}
}
TOTP Check
checks: {
totp: {
code: '123456'
}
}
WebAuthn Check
checks: {
web_auth_n: {
credential_assertion_data: 'base64_encoded_data'
}
}
IDP Check
checks: {
idp_intent: {
idp_intent_id: 'intent_id',
idp_intent_token: 'token'
}
}
metadata: {
user_agent: request.user_agent,
ip_address: request.remote_ip,
device_id: 'device_123',
location: 'US-CA',
custom_field: 'custom_value'
}
Session Lifetime
Control session duration:
# 1 hour session
lifetime: '3600s'
# 24 hour session
lifetime: '86400s'
# Use default instance settings
lifetime: nil
Use Cases
Creating a Password Session
request = Zitadel::Client::Models::BetaSessionServiceCreateSessionRequest.new(
checks: {
user: { login_name: '[email protected]' },
password: { password: 'secure_password' }
}
)
response = session_service.create_session(request)
Adding MFA to Existing Session
request = Zitadel::Client::Models::BetaSessionServiceSetSessionRequest.new(
session_id: 'session_123456',
checks: {
totp: { code: '123456' }
}
)
response = session_service.set_session(request)
Listing User Sessions
request = Zitadel::Client::Models::BetaSessionServiceListSessionsRequest.new(
queries: [
{ user_id_query: { user_id: '123456789' } }
]
)
response = session_service.list_sessions(request)
Logging Out (Terminating Session)
request = Zitadel::Client::Models::BetaSessionServiceDeleteSessionRequest.new(
session_token: user_session_token
)
session_service.delete_session(request)
Migration Guide
To migrate to Session Service v2:
- Replace
BetaSessionServiceApi with SessionServiceV2Api
- Update check structures in requests
- Review session token handling
- Test authentication flows
See Also
