OnetimeSecret Ruby Client

The official Ruby client for the OnetimeSecret API. Share sensitive information through a link that can only be viewed once.

• Zero runtime dependencies — built entirely on the Ruby standard library (net/http, uri, json), so it drops into any environment without pulling transitive gems.
• Supports API v1 and v2 — pick a version per client. The same resource methods exist for both, but each version returns its own response shape (they are different APIs; the client does not normalize them). v1 is deprecated and included only because the service still serves it — use v2 for new work.
• Ruby 3.1+.

The onetime command-line tool has moved to a separate onetime-cli gem so that this library stays dependency-free.

gem install onetime

Or in a Gemfile:

gem "onetime"

require "onetime"

client = Onetime::Client.new(
  base_url:     "https://us.onetimesecret.com", # your region's API host (required)
  organization: "on1abc...",                    # organization extid (see below)
  api_token:    ENV["ONETIME_API_TOKEN"],       # API token from your account page
  api_version:  :v2,                            # :v1 or :v2 (default :v2)
)

# Conceal a secret you already have
res = client.secrets.conceal(secret: "hunter2", ttl: 3600, passphrase: "pw")
res.dig("record", "receipt", "identifier")  # the receipt (creator) key
res.dig("record", "secret", "identifier")   # the secret (recipient) key

# Generate a random secret server-side
client.secrets.generate(ttl: 86_400)

# Reveal (consume) a secret — one-time only
secret = client.secrets.reveal("abc123secretkey", passphrase: "pw")
secret.dig("record", "secret_value")

# Service status (works on v1 and v2)
client.status

Authentication uses HTTP Basic, where the organization extid is the username and your API token is the password.

The organization extid is the identifier beginning with on shown (with a copy button) at the bottom of the user menu when you are signed in. It is no longer your email address.

base_url must be the API host for your region, your self-hosted domain, or your custom domain. There is no default: deployments are region-isolated for data sovereignty, so the client cannot guess one for you.

Regional API hosts:

The apex onetimesecret.com is the company website, not an API host, and is rejected with a helpful error.

Environment fallbacks: base_url ← ONETIME_BASE_URL; organization ← ONETIME_ORG_EXTID; api_token ← ONETIME_API_TOKEN.

Clients are thread-safe: they hold only configuration and a stateless transport, opening a fresh connection per request.

A client created without credentials is anonymous and can use public and guest endpoints:

guest = Onetime::Client.new(base_url: "https://us.onetimesecret.com")  # no credentials
guest.secrets.conceal(secret: "no account needed", guest: true)

conceal is also available as share. reveal/show accept either a bare key or a full secret URL.

client.status (v1 & v2), client.version / client.supported_locales (v2 only), client.authcheck (v1 only).

Resource methods return an Onetime::Response with indifferent (String or Symbol) key access:

res = client.secrets.conceal(secret: "hi")
res["record"]                                   # Hash
res.dig(:record, :secret, :secret_value)        # deep access
res.success?                                     # 2xx?
res.http_status                                  # Integer
res.to_h                                         # the parsed body

The response shape is the API's, unchanged. v1 and v2 differ on purpose — v1 returns flat, all-string fields; v2 nests data under record/details with richer typing — and the client does not reconcile them. Read the API docs for the shape of the version you target.

HTTP errors (status >= 400) raise typed exceptions following the API's ADR-013 error contract ({ error:, error_type:, ... }):

begin
  client.secrets.reveal("missing")
rescue Onetime::NotFoundError => e
  e.message      # human-readable message ("error" field)
  e.error_type   # machine-readable type ("RecordNotFound")
  e.http_status  # 404
rescue Onetime::RateLimitError => e
  e.retry_after
rescue Onetime::APIError => e
  # any other API error
end

All inherit from Onetime::Error.

bundle install
rake test

See LICENSE.txt.