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:

Summary

Authlete API: Welcome to the Authlete API documentation. Authlete is an API-first service where every aspect of the platform is configurable via API. This documentation will help you authenticate and integrate with Authlete to build powerful OAuth 2.0 and OpenID Connect servers.

At a high level, the Authlete API is grouped into two categories:

  • Management APIs: Enable you to manage services and clients.
  • Runtime APIs: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.

🌐 API Servers

Authlete is a global service with clusters available in multiple regions across the world:

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

Our customers can host their data in the region that best meets their requirements.

🔑 Authentication

All API endpoints are secured using Bearer token authentication. You must include an access token in every request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Getting Your Access Token

Authlete supports two types of access tokens:

Service Access Token - Scoped to a single service (authorization server instance)

  1. Log in to Authlete Console
  2. Navigate to your service → Settings → Access Tokens
  3. Click Create Token and select permissions (e.g., service.read, client.write)
  4. Copy the generated token

Organization Token - Scoped to your entire organization

  1. Log in to Authlete Console
  2. Navigate to Organization Settings → Access Tokens
  3. Click Create Token and select org-level permissions
  4. Copy the generated token

⚠️ Important Note: Tokens inherit the permissions of the account that creates them. Service tokens can only access their specific service, while organization tokens can access all services within your org.

Token Security Best Practices

  • Never commit tokens to version control - Store in environment variables or secure secret managers
  • Rotate regularly - Generate new tokens periodically and revoke old ones
  • Scope appropriately - Request only the permissions your application needs
  • Revoke unused tokens - Delete tokens you're no longer using from the console

Quick Test

Verify your token works with a simple API call:

curl -X GET https://us.authlete.com/api/service/get/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

🎓 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

The SDK can be installed using RubyGems:

gem install authlete_ruby_sdk

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

Example

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
    )

res = s.services.retrieve(service_id: '<id>')

unless res.service.nil?
  # handle response
end

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 the bearer parameter must be set when initializing the SDK client instance. For example:

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
    )

res = s.services.retrieve(service_id: '<id>')

unless res.service.nil?
  # handle response
end

Available Resources and Operations

Available methods

Authorization

AuthorizationManagement

Ciba

ClientManagement

Clients

DeviceFlow

DynamicClientRegistration

Federation

GrantManagement

HardwareSecurityKeys

Introspection

JoseObject

JWKSetEndpoint

Lifecycle

NativeSso

PushedAuthorization

  • create - Process Pushed Authorization Request

Revocation

Services

TokenOperations

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
s = ::Authlete::Client.new(
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
    )

begin
    res = s.services.retrieve(service_id: '<id>')

    unless res.service.nil?
      # handle response
    end
rescue Models::Errors::ResultError => e
  # handle e.container data
  raise e
rescue Models::Errors::ResultError => e
  # handle e.container data
  raise e
rescue Errors::APIError => e
  # handle default exception
  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

Select Server by Index

You can override the default server globally by passing a server index to the server_idx (Integer) optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:

# 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
s = ::Authlete::Client.new(
      server_idx: 0,
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
    )

res = s.services.retrieve(service_id: '<id>')

unless res.service.nil?
  # handle response
end

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the server_url (String) optional parameter when initializing the SDK client instance. For example:

require 'authlete_ruby_sdk'

Models = ::Authlete::Models
s = ::Authlete::Client.new(
      server_url: 'https://br.authlete.com',
      bearer: '<YOUR_BEARER_TOKEN_HERE>',
    )

res = s.services.retrieve(service_id: '<id>')

unless res.service.nil?
  # handle response
end

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 8

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

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages