Skip to content

authlete/authlete-ruby-sdk

BranchesTags

Repository files navigation

Authlete Ruby SDK

Developer-friendly & type-safe Ruby SDK specifically catered to leverage Authlete API v3.0 and forward.

Important

This is a beta SDK.

🎓 Tutorials

If you're new to Authlete or want to see sample implementations, these resources will help you get started:

🛠 Contact Us

If you have any questions or need assistance, our team is here to help:

Table of Contents

SDK Installation

Prerequisites

  • Ruby Version: Ruby >= 3.2.0 is required 
    ruby --version  # Check your Ruby version

Install the SDK

The SDK can be installed using RubyGems:

gem install authlete_ruby_sdk

Or add it to your Gemfile:

gem 'authlete_ruby_sdk', '~> 0.0.2.beta'

Then run:

bundle install

Access Tokens

You need to pass a valid access token to be able to use any resource or operation. The bearer parameter required when initializing the SDK client must be one of the following two token types:

  • Service Access Token - Scoped to a single service (authorization server instance). Use when you need to access a specific service only. Create from Service Settings → Access Tokens in the Authlete Console.
  • Organization Token - Scoped to your entire organization, allowing access to all services. Use when you need to access multiple services or perform organization-level operations. Create from Organization Settings → Access Tokens.

Refer to Creating an Access Token to learn how to create one.

Troubleshooting Token Issues

If you face permission (403) errors when already sending a token, it can be one of the following problems:

  • The token you are using has expired. Check the expiry date in the Authlete Console.
  • You're using the wrong token type (e.g., using a Service Token to access a different service, or using a Service Token when you need organization-level access).
  • The resource or operation you are trying to use is not available for that service tier. For example, some features are Enterprise-only and you may be using a token for a service on a different plan.

Quick Start

Important: You must specify which Authlete server to use when initializing the client. If omitted, it defaults to the US server (server_idx: 0).

require "authlete_ruby_sdk"

# Create an alias for cleaner code (optional but recommended)
Models = ::Authlete::Models

# Initialize the Authlete client
# Available servers: https://us.authlete.com, https://jp.authlete.com, 
#                    https://eu.authlete.com, https://br.authlete.com
authlete_client = ::Authlete::Client.new(
  bearer: "<YOUR_BEARER_TOKEN>",  # Service Access Token or Organization Token (see Access Tokens section)
  server_url: "https://us.authlete.com"  # Required: Specify your server
)

# Example 1: Retrieve a service
begin
  response = authlete_client.services.retrieve(service_id: "<service_id>")
  
  unless response.service.nil?
    service = response.service
    puts "Service Name: #{service.service_name}"
    puts "Service ID (api_key): #{service.api_key}"
    puts "Issuer: #{service.issuer}"
  end
rescue Models::Errors::ResultError => e
  # Handle Authlete-specific errors
  puts "Authlete error: #{e.result_code} - #{e.result_message}"
rescue Models::Errors::APIError => e
  # Handle HTTP errors
  puts "API error: HTTP #{e.status_code} - #{e.message}"
end

# Example 2: List OAuth clients
begin
  response = authlete_client.clients.list(service_id: "<service_id>")
  
  if response.client_get_list_response && response.client_get_list_response.clients
    response.client_get_list_response.clients.each do |oauth_client|
      puts "Client: #{oauth_client.client_name} (ID: #{oauth_client.client_id})"
    end
  end
rescue Models::Errors::ResultError => e
  puts "Error: #{e.result_message}"
end

# Example 3: Process an authorization request
begin
  response = authlete_client.authorization.process_request(
    service_id: "<service_id>",
    authorization_request: Models::Components::AuthorizationRequest.new(
      parameters: "response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>"
    )
  )
  
  if response.authorization_response
    puts "Action: #{response.authorization_response.action}"
    puts "Ticket: #{response.authorization_response.ticket}" if response.authorization_response.ticket
  end
rescue Models::Errors::ResultError => e
  puts "Error: #{e.result_message}"
end

Note: Do not include /api in the server_url - the SDK appends it automatically. The service_id parameter uses the service's api_key value.

SDK Example Usage

See the Quick Start section above for comprehensive examples showing how to initialize the client and make API calls with proper error handling.

For additional examples and detailed API documentation, see the Available Resources and Operations section below.

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name Type Scheme
bearer http HTTP Bearer

To authenticate with the API, both the bearer parameter and server_url should be set when initializing the SDK client instance. For example:

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
authlete_client = ::Authlete::Client.new(
      bearer: '<YOUR_BEARER_TOKEN_HERE>',  # Service Access Token or Organization Token (see Access Tokens section)
      server_url: 'https://us.authlete.com'  # Required: Specify your server
    )

response = authlete_client.services.retrieve(service_id: '<id>')

unless response.service.nil?
  # handle response
end

Available Resources and Operations

Available methods

Authorization

AuthorizationManagement

Ciba

ClientManagement

Clients

DeviceFlow

DynamicClientRegistration

Federation

GrantManagement

HardwareSecurityKeys

Introspection

JoseObject

JWKSetEndpoint

NativeSso

PushedAuthorization

  • create - Process Pushed Authorization Request

Revocation

Services

TokenManagement

Tokens

Userinfo

VerifiableCredentials

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an error.

By default an API error will raise a Errors::APIError, which has the following properties:

Property Type Description
message string The error message
status_code int The HTTP status code
raw_response Faraday::Response The raw HTTP response
body string The response content

When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the retrieve method throws the following exceptions:

Error Type Status Code Content Type
Models::Errors::ResultError 400, 401, 403 application/json
Models::Errors::ResultError 500 application/json
Errors::APIError 4XX, 5XX */*

Example

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
authlete_client = ::Authlete::Client.new(
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
      server_url: 'https://us.authlete.com'  # Specify your server
    )

begin
    response = authlete_client.services.retrieve(service_id: '<id>')

    unless response.service.nil?
      # handle response
    end
rescue Models::Errors::ResultError => e
  # handle Authlete-specific errors
  puts "Result Code: #{e.result_code}"
  puts "Result Message: #{e.result_message}"
  raise e
rescue Errors::APIError => e
  # handle HTTP errors
  puts "Status Code: #{e.status_code}"
  puts "Body: #{e.body}"
  raise e
end

Troubleshooting

Common Issues

"cannot load such file -- sorbet-runtime"

Problem: Ruby version is too old or dependencies not installed.

Solution:

  • Ensure Ruby >= 3.2.0 is installed: ruby --version
  • Install dependencies: gem install sorbet-runtime faraday faraday-multipart faraday-retry base64

"The access token presented is not valid" (A458101)

Problem: Bearer token is invalid, expired, or lacks permissions.

Solution:

  • Verify your bearer token is correct and matches the token type you need (see Access Tokens section)
  • Check if token has expired in the Authlete Console
  • Ensure you're using the correct token type (Service Token vs Organization Token)
  • Verify you're using the correct server (token may be valid for a different region)

"Service not found" (A458203)

Problem: Service ID doesn't exist on the specified server.

Solution:

  • Verify the service ID (api_key) is correct
  • Check if you're using the correct server (service may be on a different region)
  • List services to find available service IDs: 
    response = client.services.list()
response.service_get_list_response.services.each do |s|
  puts "Service ID: #{s.api_key}, Name: #{s.service_name}"
end

"404 Not Found"

Problem: Base URL includes /api suffix or incorrect endpoint.

Solution:

  • Remove /api from server_url - use https://us.authlete.com not https://us.authlete.com/api
  • Verify the endpoint path is correct

"already initialized constant Authlete::SERVERS" (Warning)

Problem: SDK is being loaded multiple times.

Solution: This is just a warning and can be ignored. It doesn't affect functionality.

Service ID vs API Key

When calling services.retrieve(service_id: ...), use the service's api_key value as the service_id parameter:

# The service_id parameter uses the api_key value
response = client.services.retrieve(service_id: '715948317')  # api_key value
service = response.service
puts service.api_key  # Returns: 715948317

Server Selection

Important: You must configure the server URL when initializing the SDK client. If omitted, it defaults to the US server (server_idx: 0), which may not be the correct server for your services.

Configure Server URL (Recommended)

Specify the server URL directly when creating the client instance. All operations performed through that client will use the specified server.

Available Servers:

  • 🇺🇸 US: https://us.authlete.com
  • 🇯🇵 Japan: https://jp.authlete.com
  • 🇪🇺 Europe: https://eu.authlete.com
  • 🇧🇷 Brazil: https://br.authlete.com

Example

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
authlete_client = ::Authlete::Client.new(
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
      server_url: 'https://us.authlete.com'  # Specify your server
    )

response = authlete_client.services.retrieve(service_id: '<id>')

unless response.service.nil?
  # handle response
end

Note: Do not include /api in the server_url - the SDK appends it automatically.

Alternative: Select Server by Index

You can also specify the server using a numeric index instead of the full URL:

# Server Description
0 https://us.authlete.com 🇺🇸 US Cluster
1 https://jp.authlete.com 🇯🇵 Japan Cluster
2 https://eu.authlete.com 🇪🇺 Europe Cluster
3 https://br.authlete.com 🇧🇷 Brazil Cluster

Example

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
authlete_client = ::Authlete::Client.new(
      server_idx: 0,  # 0 = US, 1 = Japan, 2 = Europe, 3 = Brazil
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
    )

response = authlete_client.services.retrieve(service_id: '<id>')

unless response.service.nil?
  # handle response
end

Recommendation: Use server_url instead of server_idx for better clarity and to avoid confusion about which server you're using.

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy

About

The official Ruby SDK for Authlete API v3.0+. www.authlete.com

rubygems.org/gems/authlete_ruby_sdk

Resources

Readme

Contributing

Contributing
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 7

ruby - v0.0.2.beta - 2026-01-20 05:17:32 Latest
Jan 20, 2026
+ 6 releases

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages