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.

Installation

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

Configuration and Defaults

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.

Configuring module defaults

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

Using ENV variables

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

Variable	Description	Default
`OP_CONNECT_ACCESS_TOKEN`	The API token used to authenticate the client to a 1Password Connect API.
`OP_CONNECT_API_ENDPOINT`	The URL of the 1Password Connect API server.	http://localhost:8080/v1
`OP_CONNECT_USER_AGENT`	The user-agent string the client uses when making requests. This is optional.	1Password Connect Ruby SDK {OpConnect::VERSION}

Usage

Making requests

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

Using query parameters

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

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

👀 For more information, see the API documentation.

Consuming resources

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

List vaults

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

Get vault details

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

List items

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

Add item

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 …

Get item details

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

Replace an item

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.

Change item details

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 …

Delete an item

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

List files

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

Get file details

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

Get file content

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

List API activity

Retrieve a list of API requests made to the server.

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

Check server for a heartbeat

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

client.heartbeat
# => true

Get server health info

Query the state of the server and its service dependencies.

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

Get server metrics

This returns Prometheus metrics collected by the server.

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

Development

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.

Running a local 1Password Connect API server

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.

Resources

Some links that are definitely worth checking out:

Contributing

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.

License

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

Code of Conduct

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