Skip to main content

​
Overview

The SessionServiceApi provides methods for managing user sessions in Zitadel. Sessions can be used for authentication in OIDC/SAML requests and as OAuth2 access tokens for Zitadel APIs.

​
Initialize the API

require 'zitadel/client'

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

session_api = Zitadel::Client::Api::SessionServiceApi.new(client)

​
Session Management

Create a new session with initial checks, metadata and challenges for further verification. Returns a token which can be used for authentication.Required permission: session.write
request = Zitadel::Client::SessionServiceCreateSessionRequest.new(
  checks: {
    user: {
      user_id: 'user_123'
    },
    password: {
      password: 'user_password'
    }
  },
  metadata: {
    'device_id' => 'device_123',
    'ip_address' => '192.168.1.1'
  }
)

response = session_api.create_session(request)
puts "Session ID: #{response.session_id}"
puts "Session Token: #{response.session_token}"
​
session_id
string
The ID of the created session
​
session_token
string
The token to use for authentication
Update an existing session with new information like additional checks or metadata. Returns a new session token.Required permission: session.write
request = Zitadel::Client::SessionServiceSetSessionRequest.new(
  session_id: 'session_123',
  session_token: 'current_token',
  checks: {
    totp: {
      code: '123456'
    }
  },
  metadata: {
    'mfa_verified' => 'true'
  }
)

response = session_api.set_session(request)
puts "New Session Token: #{response.session_token}"
Retrieve a session by its ID. Returns all information about the session including factors, metadata, and user agent.
request = Zitadel::Client::SessionServiceGetSessionRequest.new(
  session_id: 'session_123',
  session_token: 'current_token' # Optional if you have permission
)

response = session_api.get_session(request)
puts "User ID: #{response.session.factors.user.id}"
puts "Created: #{response.session.creation_date}"
puts "Expiration: #{response.session.expiration_date}"
Searches for sessions matching the given query. Can search by session ID, user ID, creation date, and more.Required permission: session.read
request = Zitadel::Client::SessionServiceListSessionsRequest.new(
  queries: [{
    user_id_query: {
      id: 'user_123'
    }
  }]
)

response = session_api.list_sessions(request)
response.result.each do |session|
  puts "Session: #{session.id}, Created: #{session.creation_date}"
end
Terminate an existing session. This invalidates the session and its token.Required permission: session.delete (or no permission for own sessions)
request = Zitadel::Client::SessionServiceDeleteSessionRequest.new(
  session_id: 'session_123',
  session_token: 'current_token' # Optional if you have permission
)

response = session_api.delete_session(request)

​
Session Checks

Sessions support various authentication checks:

​
User Check

checks: {
  user: {
    user_id: 'user_123'
  }
}

​
Password Check

checks: {
  password: {
    password: 'user_password'
  }
}

​
TOTP/OTP Check

checks: {
  totp: {
    code: '123456'
  }
}

​
WebAuthn/Passkey Check

checks: {
  web_auth_n: {
    credential_assertion_data: 'assertion_data'
  }
}

​
Example: Multi-Factor Authentication Flow

# Step 1: Create session with password
request = Zitadel::Client::SessionServiceCreateSessionRequest.new(
  checks: {
    user: { user_id: 'user_123' },
    password: { password: 'user_password' }
  }
)

response = session_api.create_session(request)
session_id = response.session_id
session_token = response.session_token

# Step 2: Add TOTP verification
mfa_request = Zitadel::Client::SessionServiceSetSessionRequest.new(
  session_id: session_id,
  session_token: session_token,
  checks: {
    totp: { code: '123456' }
  }
)

mfa_response = session_api.set_session(mfa_request)
final_token = mfa_response.session_token

puts "Authenticated with MFA. Token: #{final_token}"

​
Example: Session with Metadata

request = Zitadel::Client::SessionServiceCreateSessionRequest.new(
  checks: {
    user: { user_id: 'user_123' },
    password: { password: 'user_password' }
  },
  metadata: {
    'device_type' => 'mobile',
    'device_id' => 'iphone_12',
    'app_version' => '1.2.3',
    'ip_address' => '192.168.1.1',
    'location' => 'San Francisco, CA'
  }
)

response = session_api.create_session(request)

​
Using Sessions for Authentication

Session tokens can be used in multiple ways:

​
As OAuth2 Access Token

# Use the session token as a bearer token
headers = {
  'Authorization' => "Bearer #{session_token}"
}

​
For OIDC Authentication

Pass the session token as the id_token_hint parameter in OIDC authorization requests.

​
For SAML Authentication

Session tokens can be used to authenticate SAML requests.

​
Session Lifecycle

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us