Skip to main content
The OIDCServiceApi provides methods for handling OpenID Connect (OIDC) authentication flows, including authorization requests, callbacks, and device authorization.

​
Initialize the API

Access the OIDC Service through the Zitadel client: 
require 'zitadel-client'

client = Zitadel::Client::Zitadel.with_access_token(
  "https://example.us1.zitadel.cloud",
  "your-access-token"
)

# Access OIDC service
oidc_service = client.oidc

​
Methods

​
get_auth_request

Get OIDC Auth Request details by ID from the redirect URL.
​
auth_request_id
string
required
The ID of the authentication request obtained from the redirect URL
request = Zitadel::Client::OIDCServiceGetAuthRequestRequest.new(
  auth_request_id: "auth_request_id_from_redirect"
)

response = client.oidc.get_auth_request(request)
puts "Auth Request: #{response.auth_request}"
Required permissions: session.read

​
create_callback

Finalize an Auth Request and get the callback URL for success or failure. The user must be redirected to this URL to inform the application.
​
auth_request_id
string
required
The ID of the authentication request to finalize
​
callback_url
string
required
The callback URL configured for the application
request = Zitadel::Client::OIDCServiceCreateCallbackRequest.new(
  auth_request_id: "auth_request_id",
  callback_url: "https://your-app.com/callback"
)

response = client.oidc.create_callback(request)
puts "Callback URL: #{response.callback_url}"
puts "State: #{response.state}"
Required permissions: session.link
This method can only be called once per Auth Request

​
get_device_authorization_request

Get Device Authorization Request details by ID.
​
device_authorization_request_id
string
required
The ID of the device authorization request
request = Zitadel::Client::OIDCServiceGetDeviceAuthorizationRequestRequest.new(
  device_authorization_request_id: "device_auth_id"
)

response = client.oidc.get_device_authorization_request(request)
puts "Device Code: #{response.device_code}"
puts "User Code: #{response.user_code}"
Required permissions: session.read

​
authorize_or_deny_device_authorization

Authorize or deny a device authorization request.
​
device_authorization_request_id
string
required
The ID of the device authorization request
​
approved
boolean
required
Whether to approve or deny the authorization request
request = Zitadel::Client::OIDCServiceAuthorizeOrDenyDeviceAuthorizationRequest.new(
  device_authorization_request_id: "device_auth_id",
  approved: true
)

response = client.oidc.authorize_or_deny_device_authorization(request)
puts "Authorization processed"
Required permissions: session.link

​
Common Use Cases

​
Implementing Custom Login UI

# 1. Get auth request details
auth_request = client.oidc.get_auth_request(
  Zitadel::Client::OIDCServiceGetAuthRequestRequest.new(
    auth_request_id: params[:auth_request_id]
  )
)

# 2. Display your custom login UI and authenticate the user
# ... your authentication logic ...

# 3. Create callback after successful authentication
callback_response = client.oidc.create_callback(
  Zitadel::Client::OIDCServiceCreateCallbackRequest.new(
    auth_request_id: params[:auth_request_id],
    callback_url: auth_request.callback_url
  )
)

# 4. Redirect user to callback URL
redirect_to callback_response.callback_url

​
Device Authorization Flow

# Device generates authorization request
# ... device flow initialization ...

# User enters user code on another device
# 1. Get authorization details
device_auth = client.oidc.get_device_authorization_request(
  Zitadel::Client::OIDCServiceGetDeviceAuthorizationRequestRequest.new(
    device_authorization_request_id: user_code
  )
)

# 2. Show authorization prompt to user
puts "Authorize #{device_auth.client_name}?"

# 3. Process user's decision
client.oidc.authorize_or_deny_device_authorization(
  Zitadel::Client::OIDCServiceAuthorizeOrDenyDeviceAuthorizationRequest.new(
    device_authorization_request_id: user_code,
    approved: user_approved?
  )
)

​
Best Practices

Always validate the state parameter in callbacks to prevent CSRF attacks
The create_callback method can only be called once per Auth Request. Attempting to call it again will result in an error.
Auth Request IDs are typically obtained from the redirect URL when users are sent to your custom login page

​
Error Handling

begin
  response = client.oidc.create_callback(request)
rescue Zitadel::Client::ApiError => e
  case e.code
  when 400
    puts "Invalid request: #{e.message}"
  when 404
    puts "Auth request not found or already processed"
  when 403
    puts "Insufficient permissions"
  else
    puts "Error: #{e.message}"
  end
end

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us