Ruby SDK

The Ruby SDK provides helpers for the full pre-execution authorization flow: create a client, authorize an action, handle the three outcomes, and verify the permit before execution.

Install

gem install veritrellis

Or add it to your Gemfile:

Gemfile

gem "veritrellis"

Requires Ruby 3.0 or later.

require "veritrellis"

Quick reference

Symbol	Purpose
Veritrellis::Client.new(...)	Initialize a scoped client
client.authorize(...)	Submit an action for authorization
client.verify_permit(permit)	Verify a permit JWT
client.poll_permit(request_id)	Poll for a pending permit

---

Create a client

client.rb

require "veritrellis"

client = Veritrellis::Client.new(
  api_key: ENV.fetch("VERITRELLIS_API_KEY"),
  workspace_id: ENV.fetch("VERITRELLIS_WORKSPACE_ID"),
  environment: "sandbox", # "sandbox" | "production"
  api_url: "https://api.veritrellis.ai"
)

Configuration

Option	Type	Required	Description
api_key	String	Yes	Workspace API key (vt_sandbox_… or vt_prod_…)
workspace_id	String	Yes	Your workspace ID (ws_…)
environment	String	Yes	"sandbox" or "production"; must match the API key
api_url	String	No	Defaults to https://api.veritrellis.ai

---

Authorize an action

Call this before any action that requires a permit. It contacts the Veritrellis API and returns one of three outcomes.

refund.rb

result = client.authorize(
  action_type: "issue_refund",
  resource_ref: "cus_123",
  payload: {
    customer_id: "cus_123",
    amount: 75,
    currency: "EUR",
    reason: "customer request"
  }
)

Handling the three outcomes

handle_outcomes.rb

case result[:decision]
when "allowed"
  # Permit is ready — verify it before executing
  claims = client.verify_permit(result[:permit])
  # Proceed with the action using verified claims
  issue_refund(claims)

when "pending_approval"
  # Save result[:request_id] and poll GET /v1/permits/:request_id
  save_for_polling(result[:request_id])

when "denied"
  # Policy blocked this request — do not execute
  raise "Action denied: #{result[:reason_code]}"
end

Always verify the permit

Receiving a permit from authorize is not sufficient. You must call verify_permit before executing the action. Permits that fail verification must not unlock execution.

Request parameters

Parameter	Type	Required	Description
action_type	String	Yes	The canonical action type (e.g. issue_refund)
resource_ref	String	Yes	Identifier of the resource being acted on
payload	Hash	Yes	Action-specific fields; validated against shared schemas
actor_ref	String	No	ID of the human or agent initiating the action
idempotency_key	String	No	Stable key for safe retries

Response shape

The result is a hash:

Key	Present when	Type	Description
:decision	Always	String	"allowed", "pending_approval", or "denied"
:request_id	Always	String	Unique request identifier
:permit	allowed only	String	Signed ES256 permit JWT
:reason_code	denied only	String	Machine-readable denial reason

---

Verify a permit

Verifies a permit JWT against the workspace JWKS. The client already holds the workspace ID and issuer. Raises if the signature, issuer, audience, or expiry check fails.

verify.rb

claims = client.verify_permit(result[:permit])

Pass expected_action_type: to also assert the permit authorizes a specific action:

claims = client.verify_permit(result[:permit], expected_action_type: "issue_refund")

The returned claims contains:

Claim	Type	Description
:sub	String	Request ID this permit is bound to
:workspace_id	String	Workspace the permit was issued for
:action_type	String	Action type the permit authorizes
:resource_ref	String	Resource the permit is scoped to
:iat	Integer	Issued-at timestamp (Unix)
:exp	Integer	Expiry timestamp (Unix)

---

Polling for a permit

When result[:decision] is pending_approval, poll until the request resolves:

poll.rb

permit = client.poll_permit(result[:request_id])
# Ready — verify before executing
claims = client.verify_permit(permit)

poll_permit returns the permit once approved, and raises if the request is denied or expires.

---

Environment variables

Variable	Required	Description
VERITRELLIS_API_KEY	Yes	API key from the admin app
VERITRELLIS_WORKSPACE_ID	Yes	Workspace ID from the admin app

Using .env files

Both the API key and workspace ID are available in the admin app under Settings > API keys. The sandbox and production environments have separate keys.

---

Source

• sdk-ruby on GitHub