1Password Connect Ruby SDK

The 1Password Connect Ruby SDK provides access to the 1Password Connect API hosted on your infrastructure. The gem is intended to be used by your applications, pipelines, and other automations to simplify accessing items stored in your 1Password vaults.

Add this line to your application's Gemfile:

gem 'op_connect'

And then execute:

bundle install

Or install it yourself as:

gem install op_connect

While OpConnect::Client accepts a range of options when creating a new client instance, OpConnect's configuration API allows you to set your configuration options at the module level. This is particularly handy if you're creating a number of client instances based on some shared defaults. Changing options affects new instances only and will not modify existing OpConnect::Client instances created with previous options.

Every writable attribute in OpConnect::Configurable can be set one at a time:

OpConnect.api_endpoint = "http://localhost:8080/v1"
OpConnect.access_token = "secret_access_token"

Or in a batch:

OpConnect.configure do |config|
  config.api_endpoint = "http://localhost:8080/v1"
  config.access_token = "secret_access_token"
end

Default configuration values are specified in OpConnect::Default. Many attributes look for a default value from ENV before returning OpConnect's default.

API methods are available as client instance methods.

# Provide an access token
client = OpConnect::Client.new(access_token: "secret_access_token")

# Fetch a list of vaults
client.vaults

You can pass query parameters to some GET-based requests.

client.vaults filter: "title eq 'Secrets Automation'"

👀 For more information, see the API documentation.

Most methods return an object which provides convenient dot notation for fields returned in the API response.

vaults = client.vaults
# => [#<OpConnect::Vault:0x00007fae27198610 …
vaults.first.id
# => "alynbizzypgx62nti6zxajloei"

vault = client.vault(id: "alynbizzypgx62nti6zxajloei")
# => #<OpConnect::Vault:0x00007fae200c1a18 …

items = client.items(vault_id: vault.id)
# => [#<OpConnect::Item:0x00007fae27151490 …

The request must include a FullItem object containing the information to create the item.

👀 See the API documentation for an example.

attributes = {
  vault: {
    id: vault.id
  },
  title: "Secrets Automation Item",
  category: "LOGIN",
  fields: [
    {
      value: "wendy",
      purpose: "USERNAME"
    },
    {
      purpose: "PASSWORD",
      generate: true,
      recipe: {
        length: 55,
        characterSets: ["LETTERS", "DIGITS"]
      }
    }
  ]
  # …
}

item = client.create_item(vault_id: vault.id, body: attributes)
# => #<OpConnect::Item:0x00007fae27151490 …

item = client.item(vault_id: vault.id, id: "yqthoh76cfzpbsimk6zixshosq")
# => #<OpConnect::Item:0x00007fae27151490 …
item.title
# => "AWS IAM Account"
item.favorite?
# => false

attributes = {
  vault: {
    id: vault.id
  },
  title: "Secrets Automation Item",
  category: "LOGIN",
  fields: [
    {
      value: "jonathan",
      purpose: "USERNAME"
    },
    {
      purpose: "PASSWORD",
      generate: true,
      recipe: {
        length: 55,
        characterSets: ["LETTERS", "DIGITS"]
      }
    }
  ]
  # …
}

item = client.replace_item(vault_id: vault.id, id: item.id, body: attributes)
# => #<OpConnect::Item:0x00007fae27151490 …

👀 See the API documentation for an explanation and list of fields and object structure.

Use the JSON Patch document standard to compile a series of operations to make more targeted changes to an item.

👀 See the API documentation for more information.

attributes = [
  {op: "replace", path: "/title", value: "New Secrets Automation Item"},
  {op: "replace", path: "/fields/username", value: "tinkerbell"}
]

item = client.update_item(vault_id: vault.id, id: item.id, body: attributes)
# => #<OpConnect::Item:0x00007fae27151490 …

client.delete_item(vault_id: vault.id, id: item.id)
# => true

files = client.files(vault_id: vault.id, item_id: item.id)
# => [#<OpConnect::Item::File:0x00007fae27151490 …

file = client.file(vault_id: vault.id, item_id: item.id, id: "6r65pjq33banznomn7q22sj44e")
# => #<OpConnect::Item::File:0x00007fae27151490 …

content = client.file(vault_id: vault.id, item_id: item.id, id: file.id)
# => "The future belongs to the curious.\n"

Retrieve a list of API requests made to the server.

client.activity
# => [#<OpConnect::APIRequest:0x00007fae27151490 …

Ping the server to check if it's active or not.

client.heartbeat
# => true

Query the state of the server and its service dependencies.

client.health
# => #<OpConnect::ServerHealth:0x00007fae27151490 …

This returns Prometheus metrics collected by the server.

client.metrics
# => "# HELP go_gc_duration_seconds A summary of the pause duration of …

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

This project includes a docker-compose.yml file that will download and run an API and Sync server for you to test with locally. You will need to:

• Install Docker, Docker for Mac, or Docker for Windows.
• Place your 1password-credentials.json file in the root of this project.

👀 See Get started with a 1Password Secrets Automation workflow for more information.

Some links that are definitely worth checking out:

• 1Password Secrets Automation
• Get started with a 1Password Secrets Automation workflow
• 1Password Connect API reference

Bug reports and pull requests are welcome on GitHub at https://github.com/partydrone/connect-sdk-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Connect project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.